Skip to main content

Limited access tokens

Limited access tokens support access to the Verified Orchestration platform API from a client application (e.g. a browser or mobile app, where an API access secret cannot be stored securely). This avoids the need to proxy API requests and callbacks through a secure back-end application.

Limited access tokens have limited lifetime and capability, for example:

  • Issue one or more pre-selected credentials to a single identity
  • Request and receive presentations of one or more pre-selected credential types;
    • either from a known identity, or
    • anonymously
  • Query limited data related to the issuance or presentation

Example: issuance or presentation for a known user​

example: issuance or presentation for a known userexample: issuance or presentation for a known user

Setup for limited access tokens​

Before you can acquire limited access tokens, a platform administrator must grant your secure backend API one or more roles:

  • VerifiableCredential.AcquireLimitedAccessToken.Issue provides access to acquire limited access tokens for issuance operations
  • VerifiableCredential.AcquireLimitedAccessToken.Present provides access to acquire limited access tokens for presentation operations
  • VerifiableCredential.AcquireLimitedAccessToken.AnonymousPresentations provides access to acquire limited access tokens for anonymous presentation operations
  • VerifiableCredential.AcquireLimitedAccessToken.ListContracts provides access to acquire limited access tokens for listing contracts.

For detailed info on onboarding your secure backend API, refer to the Onboarding guide.

Acquiring a limited access token​

The acquireLimitedAccessToken mutation returns an access token with specific capabilities according to the AcquireLimitedAccessTokenInput:

Issuance tokens​

Issuance tokens require:

  • a reference to the identity to which access (issuance and related data) will be limited
  • a list of one or more contracts that can be issued with the token

Presentation tokens​

Presentation tokens require:

  • a reference to the identity to which access (presentation and related data) will be limited
  • a list of the credentials that can be requested

Note:

  • the presentation callback can optionally be defined in the limited access token input by the secure backend API, so that the client application does not need to provide it and it cannot be tampered with.

Anonymous presentation tokens​

Anonymous presentation tokens require:

  • a list of the credentials that can be requested

API usage​

acquireLimitedAccessToken returns the access token and expiry
mutation AcquireLimitedAccessToken($input: AcquireLimitedAccessTokenInput!) {
  acquireLimitedAccessToken(input: $input) {
    expires
    token
  }
}
Example input for issuance + list contracts
const identity = await saveIdentity()
const variables: AcquireLimitedAccessTokenInput = {
  input: {
    identityId: savedIdentity.id,
    issuableContractIds: contractIds,
    listContracts: true,
  },
}
Example input for presentation
const identity = await saveIdentity()
const variables: AcquireLimitedAccessTokenInput = {
  input: {
    identityId: savedIdentity.id,
    requestableCredentials: [{ credentialType: 'VerifiedEmployee' }],
    callback: {
      url: 'https://secure-backend.example/presentation/callback',
      headers: {
        Authorization: 'Bearer {token}',
      },
    },
  },
}
Example input for anonymous presentations
const variables: AcquireLimitedAccessTokenInput = {
  input: {
    allowAnonymousPresentation: true,
    requestableCredentials: [{ credentialType: 'VerifiedEmployee' }, { credentialType: 'VerifiedContractor' }],
  },
}

A sample implementation of the backend API for acquiring limited access tokens from the Verified Orchestration platform using Node.JS is provided in the Secure backend API guide.

Saving an identity reference​

For applications where there is a known (authenticated) user, an identity reference must be supplied to limit the scope of limited issuance or presentation tokens. Anonymous presentation tokens do not require an identity reference.

saveIdentity mutation creates (or updates) an identity
mutation SaveIdentity($input: IdentityInput!) {
  saveIdentity(input: $input) {
    id
    name
  }
}
Example creating an identity based on a logged-in user
public async saveIdentity(user: User) {
  const variables = {
    input: {
      identifier: user.id,
      issuer: user.claims.iss,
      name: user.name,
    },
  }

  const result = await this.client.mutate({ mutation: saveIdentityMutation, variables: variables })
  return result.data.saveIdentity
}

Limited access to data​

Limited access tokens can be used to query data related to the issuance or presentation and identity, however other data is not accessible.

Subscribe to issuance event using the requestId of the issuance request
subscription IssuanceEvent($requestId: ID!) {
  issuanceEvent(where: {requestId: $requestId}) {
    event {
      requestStatus
      error {
        code
        message
      }
    }
    issuance {
      id
      expiresAt
      contract {
        id
        name
        ...
      }
    }
  }
}
Query (poll) for issuances using the requestId of the issuance request
query FindIssuance($requestId: ID!) {
  findIssuances(where: { requestId: $requestId }, limit: 1) {
    id
    issuedAt
    expiresAt
    contract {
      id
      name
      ...
    }
  }
}
List contracts with the most recent issuance for the specified identity
query FindContracts($where: ContractWhere, $forIdentityId: ID!) {
  findContracts(where: $where) {
    id
    display {
      card {
        title
        issuedBy
        backgroundColor
        textColor
        description
        logo {
          uri
          description
        }
      }
    }
    issuances(where: { identityId: $forIdentityId }, limit: 1) {
      id
      issuedAt
      credentialExpiresAt
    }
  }
}