Skip to main content
European CommissionEBSI European Blockchain

How to obtain an access token

Last updated on

Introduction

The Authorisation API 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.

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 API utilises the following capabilities:

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 Trusted Issuer Registry.

  • Anonymous users only have access to read public information, allowing them to call all the REST endpoints, but not the JSON-RPC endpoints.

For more information, refer to:

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 <domain>_<intent>[_<nominator>].

Presentation Definition

Each identified scope has unique Verifiable Presentation definition requirements. A GET HTTP endpoint is exposed, as defined in openid-configuration under the presentation_definition_endpoint claim, where the client can obtain the presentation definition for the requested scope. The following scopes are supported:

  • SCOPES
IntentScopeTypeDescriptionAuthorisation
Add DID documentdidr_writeFallbackGrants write access to DID RegistryGranted When VP contains only a valid VerifiableAuthorisationToOnboard, issued by Root TAO or TAO.
Add Trusted Issuer Registry contenttir_writePrivilegedGrants write access to TIR.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
AbbreviationTermDescription
EBSI SOEBSI Support OfficeTechnical support team within EBSI
RTAORoot Trusted Accreditation OrganisationEntity that issues Verifiable Accreditations for Trusted Accreditation Organisations
TAOTrusted Accreditation OrganisationEntity that issues Verifiable Accreditations (Accreditations, Attestations and Authorisations) to legal entities
TITrusted IssuerLegal Entity with one or more accreditations. Accredited to accredit, attest or authorise

  • REGISTRIES
NameRole
DID Registry (DIDR)Stores registered DIDs
Trusted Issuers Registry (TIR)Stores registered accreditations from TIs

  • POLICIES
APIScopeRequired Verifiable CredentialGranted AccessMethods to be used
DIDRdidr_writeNo credentials are required, but the requestor must be a Trusted Issuer.Full control over the DID Registry and Trusted Issuers RegistryinsertDidDocument / updateBaseDocument / addController / revokeController / addVerificationMethod / addVerificationRelationship / revokeVerificationMethod / expireVerificationMethod / rollVerificationMethod
DIDRdidr_inviteVerifiableAuthorisationToOnboardRegistration of DID into the DID RegistryinsertDidDocument: didr_invite + AT.sub == req.params.did (the DID to be inserted)
TIRtir_writeNo credentials are required, but the requestor must be a Trusted Issuer.Full control over the DID Registry and Trusted Issuers RegistryinsertIssuer / updateIssuer / setAttributeMetadata / setAttributeData / insertPolicy / updatePolicy / addIssuerProxy / updateIssuerProxy
TIRtir_inviteVerifiableAuthorisationForTrustChain or VerifiableAccreditationToAttest or VerifiableAccreditationToAccreditRegistration of VC into the Trusted Issuers RegistrysetAttributeData: tir_invite + AT.sub == req.params.did (the DID to be inserted)

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:

Note: didr_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 EBSI 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'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:

Get presentation definition requirements

Fetches presentation definition requirements. For a detailed description of this endpoint, please refer to the documentation here:

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: