Access Control

This page details how to obtain the authorisation to access EBSI APIs.

The Authorisation Service is a core EBSI service responsible for managing access to protected EBSI services. To receive a short-lived access token with a two-hour lifespan, a legal entity must present a valid Verifiable Authorisation or Verifiable Accreditation in the form of a Verifiable Presentation (VP). The access token's scope is limited and corresponds to the specific authorisations of the legal entity.

info

Consult the Authorisation Service page for API instructions on how to register your DID on the Issuers Registry.

Users obtain access tokens by presenting a valid EBSI Verifiable Credential and proving ownership over their DID. During the onboarding process, when a user does not yet have ownership of a DID, presenting a VerifiableAuthorisationToOnboard is sufficient.

The Authorisation Service utilises the following capabilities:

Authorisation Server discovery via the /.well-known/openid-configuration
OpenID for Verifiable Presentations capabilities (1.0 final, DCQL)
OIDC capabilities (v1.0)

Supported OpenID4VP grants

The Authorisation Service implements the OpenID4VP 1.0 (final) grant, which uses a DCQL query. The legacy OpenID4VP draft 14 grant (Presentation Exchange, with a Presentation Definition and a presentation_submission) is no longer supported: the /auth/presentation-definitions endpoint has been removed, and a compact-JWS vp_token is rejected with invalid_request. See the migration guide.

The EBSI Platform differentiates between identified and anonymous users, each with a unique set of intents.

Identified users are legal entities that utilise the trusted registries - the DID Registry and Issuers Registry.
Anonymous users only have access to read public information, allowing them to call all the REST endpoints, but not the Ledger Service's JSON-RPC endpoint when the invoked method is not public.

Mechanism

Within EBSI, DIDs serve as identity identifiers. Proof of DID ownership is established via the exchange of Verifiable Presentations.

Access management is divided into two components:

Endpoint protection - Filters intents to manage access.
Entity protection - Applies business logic-based rules.

Please note, access is always intent-based, which is manifested as an OAuth 2.0 scope.

Scopes must conform to the pattern of <registry>:<action>, optionally suffixed with :<0x-address> to target a specific contract instance instead of the environment's default.

Scopes, actors, registries and policies

Each identified scope has unique Verifiable Presentation requirements, which the client obtains from the DCQL query endpoint. The following scopes are supported:

SCOPES

Intent	Scope	Type	Description	Authorisation
Add DID document	did-registry:write	Fallback	Grants write access to DID Registry	Granted When VP contains only a valid VerifiableAuthorisationToOnboard, issued by Root TAO or TAO.
Add Issuers Registry content	issuers-registry:write	Privileged	Grants write access to the Issuers Registry.	Granted when VP contains a valid VerifiableAuthorisationForTrustChain from EBSI TO, or a Verifiable Accreditation (VerifiableAccreditationToAttest, or VerifiableAccreditationToAccredit), issued by Root TAO or TAO.

Unrecognised scopes will return an error.

ACTORS

Abbreviation	Term	Description
EBSI SO	EBSI Support Office	Technical support team within EBSI
RTAO	Root Trusted Accreditation Organisation	Entity that issues Verifiable Accreditations for Trusted Accreditation Organisations
TAO	Trusted Accreditation Organisation	Entity that issues Verifiable Accreditations (Accreditations, Attestations and Authorisations) to legal entities
TI	Trusted Issuer	Legal Entity with one or more accreditations. Accredited to accredit, attest or authorise

REGISTRIES

Name	Role
DID Registry	Stores registered DIDs
Issuers Registry	Stores registered accreditations from TIs

POLICIES

API	Scope	Required Verifiable Credential	Granted Access	Methods to be used
DID Registry	did-registry:write	No credentials are required, but the requester must be a Trusted Issuer.	Full control over the DID Registry and Issuers Registry	insertDidDocument / updateBaseDocument / addController / revokeController / addVerificationMethod / addVerificationRelationship / revokeVerificationMethod / expireVerificationMethod / rollVerificationMethod
DID Registry	did-registry:invite	VerifiableAuthorisationToOnboard	Registration of DID into the DID Registry	insertDidDocument: did-registry:invite + AT.sub == req.params.did (the DID to be inserted)
Issuers Registry	issuers-registry:write	No credentials are required, but the requester must be a Trusted Issuer.	Full control over the DID Registry and Issuers Registry	insertIssuer / updateIssuer / setAttributeMetadata / setAttributeData / insertPolicy / updatePolicy / addIssuerProxy / updateIssuerProxy
Issuers Registry	issuers-registry:invite	VerifiableAuthorisationForTrustChain or VerifiableAccreditationToAttest or VerifiableAccreditationToAccredit	Registration of VC into the Issuers Registry	setAttributeData: issuers-registry:invite + AT.sub == req.params.did (the DID to be inserted)

DCQL Query

The OpenID4VP 1.0 (final) grant uses a DCQL (Digital Credentials Query Language) query, as defined in OpenID4VP 1.0 (final) §6. A GET HTTP endpoint is exposed, as defined in openid-configuration under the dcql_query_endpoint claim, where the client can obtain the DCQL query for the requested scope. Requests for combined scopes are merged into a single DCQL query.

The response contains the query itself, together with the credential formats and signing algorithms accepted by the service:

{
  "client_metadata": {
    "vp_formats_supported": {
      "jwt_vc_json": {
        "alg_values_supported": ["ES256K"]
      }
    }
  },
  "dcql_query": {
    "credentials": [
      {
        "id": "did_registry_invite_credential",
        "format": "jwt_vc_json",
        "require_cryptographic_holder_binding": true,
        "meta": {
          "type_values": [["VerifiableAuthorisationToOnboard"]]
        }
      }
    ]
  }
}

jwt_vc_json is the only Credential Format Identifier requested by this API. The example above is the response for did-registry:invite. alg_values_supported is the algorithm accepted for the signature of the Verifiable Presentation and depends on the requested scope:

did-registry:invite and track-and-trace:authorise accept ES256K only.
All other scopes accept ES256 and ES256K.

The vp_formats_supported claim of the OpenID configuration is the union across all scopes, not a guarantee for each scope.

Signing algorithms

Compared with the pilot API, the accepted signing algorithms are now defined per scope:

Presentations are signed with ES256K for did-registry:invite and track-and-trace:authorise, and with ES256 or ES256K for every other scope. In the pilot API, ES256 was accepted for issuers-registry:invite, issuers-registry:write, policies-registry:write and schemas-registry:write only.
Credentials accept ES256 and ES256K for every scope requiring a credential. In the pilot API, they accepted ES256 only.
Scope merging no longer narrows the accepted set. In the pilot API, a combined request resolved to the intersection of the requested scopes.

CREDENTIAL QUERIES

Four scopes request a credential of a specific type. The remaining seven, which correspond to the combinable scopes, request a single shared self-attestation credential.

Scope	Credential query `id`	Requested credential type
`did-registry:invite`	`did_registry_invite_credential`	`VerifiableAuthorisationToOnboard`
`issuers-registry:invite`	`issuers_registry_invite_credential`	`VerifiableAuthorisationForTrustChain`, `VerifiableAccreditationToAttest` or `VerifiableAccreditationToAccredit`
`ledger:invoke`	`ledger_invoke_credential`	`VerifiableAuthorisationToInvoke`
`track-and-trace:authorise`	`track_and_trace_authorise_credential`	`VerifiableAuthorisationToOnboard`
`did-registry:write`, `issuers-registry:write`, `timestamp:write`, `track-and-trace:create`, `track-and-trace:write`, `policies-registry:write`, `schemas-registry:write`	`self_attestation_credential`	`SelfAttestation`

SELF-ATTESTATION CREDENTIAL

DCQL cannot express the absence of a credential requirement, since credentials must be a non-empty array. The seven combinable scopes, which require no third-party credential, therefore present a single shared, self-issued SelfAttestation credential.

The credential is issued by the holder to itself. Both iss and vc.issuer are set to the holder's own DID, as are sub and credentialSubject.id. It declares no termsOfUse and asserts no third-party trust claim, and is consequently exempt from the Issuers Registry trusted-issuer lookup. As the shared verification pipeline structurally validates every embedded credential against the EBSI Verifiable Attestation schema, the credential must nonetheless be structurally complete. The id, issuanceDate, issued, validFrom and credentialSchema properties are therefore all required, despite the credential serving only as a placeholder.

Requesting several of these scopes together results in a single credential requirement rather than one per scope.

note

The self-attestation credential is verified against the holder's capabilityInvocation verification relationship rather than assertionMethod. A newly onboarded did:ebsi grants its first key only the capabilityInvocation and authentication relationships, so requiring assertionMethod would prevent the credential from being presented until a separate, did-registry:write-scoped addVerificationRelationship transaction had been performed.

VP TOKEN

The vp_token is a JSON-encoded object keyed by DCQL credential-query id, per OpenID4VP 1.0 (final) §8.1. presentation_submission must be omitted:

{
  "self_attestation_credential": ["eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6..."]
}

A legacy compact-JWS vp_token (OpenID4VP draft 14) is rejected with invalid_request.

The Verifiable Presentation JWTs carried by the vp_token must include a nonce, an expiration time (exp) of less than 5 minutes, and an issuance time (iat) that is neither in the future nor more than 5 minutes old.

Obtaining Access

The authorisation service generates a short-lived, OAuth 2.0 compatible access token derived from the Verifiable Presentation. Due to brief session lifetimes, which are currently defined on a case-by-case basis, refresh tokens are not supported.

API CALL

Follow this sequence of API calls to request an access token.

GET DCQL query: Begin by fetching the DCQL query for the required scope.
POST Token Endpoint: Once you have the query, create and submit a vp_token keyed by the credential-query identifiers specified in the query, as a JSON object.

Note: did-registry:write scope is an exception and must be requested alone due to the validation requirements it implies.

The diagram below captures an interaction between a client and the Authorisation Service.

API Endpoints

OpenID Provider Metadata

Exposes the configuration of the OpenID Provider. For a detailed description of this endpoint, please refer to the documentation here:

OpenID Provider Metadata

OpenID Provider's public keys

Exposes the public keys used by the Authorisation Server. For a detailed description of this endpoint, please refer to the documentation here:

OpenID Provider's public keys

Get DCQL query requirements

Fetches the DCQL query requirements of a scope. For a detailed description of this endpoint, please refer to the documentation here:

Get DCQL query requirements

Get access token

Users receive access tokens by presenting a valid EBSI Verifiable Credential and proving ownership over their DID. For a detailed description of this endpoint, please refer to the documentation here:

Get access token

Mechanism​

Scopes, actors, registries and policies​

DCQL Query​

Obtaining Access​

API Endpoints​

Mechanism

Scopes, actors, registries and policies

DCQL Query

Obtaining Access

API Endpoints