Authlete Verifiable Credential Issuer API
API endpoints for implementing and running a Verifiable Credential Issuer (VCI).
OpenAPI Specification
openapi: 3.0.3
info:
title: Authlete Authorization Endpoint Verifiable Credential Issuer API
description: "Welcome to the **Authlete API documentation**. Authlete is an **API-first service** where every aspect of the \nplatform is configurable via API. This documentation will help you authenticate and integrate with Authlete to \nbuild powerful OAuth 2.0 and OpenID Connect servers.\n\nAt a high level, the Authlete API is grouped into two categories:\n\n- **Management APIs**: Enable you to manage services and clients.\n- **Runtime APIs**: Allow you to build your own Authorization Servers or Verifiable Credential (VC) issuers.\n\n## \U0001F310 API Servers\n\nAuthlete is a global service with clusters available in multiple regions across the world:\n\n- \U0001F1FA\U0001F1F8 **US**: `https://us.authlete.com`\n- \U0001F1EF\U0001F1F5 **Japan**: `https://jp.authlete.com`\n- \U0001F1EA\U0001F1FA **Europe**: `https://eu.authlete.com`\n- \U0001F1E7\U0001F1F7 **Brazil**: `https://br.authlete.com`\n\nOur customers can host their data in the region that best meets their requirements.\n\n## \U0001F511 Authentication\n\nAll API endpoints are secured using **Bearer token authentication**. You must include an access token in every request:\n\n```\nAuthorization: Bearer YOUR_ACCESS_TOKEN\n```\n\n### Getting Your Access Token\n\nAuthlete supports two types of access tokens:\n\n**Service Access Token** - Scoped to a single service (authorization server instance)\n\n1. Log in to [Authlete Console](https://console.authlete.com)\n2. Navigate to your service → **Settings** → **Access Tokens**\n3. Click **Create Token** and select permissions (e.g., `service.read`, `client.write`)\n4. Copy the generated token\n\n**Organization Token** - Scoped to your entire organization\n\n1. Log in to [Authlete Console](https://console.authlete.com)\n2. Navigate to **Organization Settings** → **Access Tokens**\n3. Click **Create Token** and select org-level permissions\n4. Copy the generated token\n\n> ⚠️ **Important Note**: Tokens inherit the permissions of the account that creates them. Service tokens can only \n> access their specific service, while organization tokens can access all services within your org.\n\n### Token Security Best Practices\n\n- **Never commit tokens to version control** - Store in environment variables or secure secret managers\n- **Rotate regularly** - Generate new tokens periodically and revoke old ones\n- **Scope appropriately** - Request only the permissions your application needs\n- **Revoke unused tokens** - Delete tokens you're no longer using from the console\n\n### Quick Test\n\nVerify your token works with a simple API call:\n\n```bash\ncurl -X GET https://us.authlete.com/api/service/get/list \\\n -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\"\n```\n\n## \U0001F393 Tutorials\n\nIf you're new to Authlete or want to see sample implementations, these resources will help you get started:\n\n- [Getting Started with Authlete](https://www.authlete.com/developers/getting_started/)\n- [From Sign-Up to the First API Request](https://www.authlete.com/developers/tutorial/signup/)\n\n## \U0001F6E0 Contact Us\n\nIf you have any questions or need assistance, our team is here to help:\n\n- [Contact Page](https://www.authlete.com/contact/)\n"
version: 3.0.16
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- description: 🇺🇸 US Cluster
url: https://us.authlete.com
- description: 🇯🇵 Japan Cluster
url: https://jp.authlete.com
- description: 🇪🇺 Europe Cluster
url: https://eu.authlete.com
- description: 🇧🇷 Brazil Cluster
url: https://br.authlete.com
security:
- bearer: []
tags:
- name: Verifiable Credential Issuer
description: API endpoints for implementing and running a Verifiable Credential Issuer (VCI).
x-tag-expanded: false
paths:
/api/{serviceId}/vci/metadata:
post:
summary: Get Verifiable Credential Issuer Metadata
description: Get verifiable credential issuer metadata
parameters:
- in: path
name: serviceId
description: A service ID.
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/vci_metadata_request'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/vci_metadata_request'
responses:
'200':
description: VCI metadata retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/vci_metadata_response'
links:
vci_offer_create:
$ref: '#/components/links/vci_offer_create'
vci_vp_metadata:
$ref: '#/components/links/vci_vp_metadata'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'500':
$ref: '#/components/responses/500'
operationId: vci_metadata_api
tags:
- Verifiable Credential Issuer
/api/{serviceId}/vci/jwtissuer:
post:
summary: Get JWT Issuer Information
description: Get JWT issuer information for VCI
parameters:
- in: path
name: serviceId
description: A service ID.
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/vci_jwtissuer_request'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/vci_jwtissuer_request'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/vci_jwtissuer_response'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'500':
$ref: '#/components/responses/500'
operationId: vci_jwtissuer_api
tags:
- Verifiable Credential Issuer
/api/{serviceId}/vci/jwks:
post:
summary: Get JSON Web Key Set
description: Get JSON Web Key Set for VCI
parameters:
- in: path
name: serviceId
description: A service ID.
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/vci_jwks_request'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/vci_jwks_request'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/vci_jwks_response'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'500':
$ref: '#/components/responses/500'
operationId: vci_jwks_api
tags:
- Verifiable Credential Issuer
/api/{serviceId}/vci/offer/create:
post:
summary: Create Credential Offer
description: Create a verifiable credential offer
parameters:
- in: path
name: serviceId
description: A service ID.
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/vci_offer_create_request'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/vci_offer_create_request'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/vci_offer_create_response'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'500':
$ref: '#/components/responses/500'
operationId: vci_offer_create_api
tags:
- Verifiable Credential Issuer
/api/{serviceId}/vci/offer/info:
post:
summary: Get Credential Offer Information
description: Get information about a verifiable credential offer
parameters:
- in: path
name: serviceId
description: A service ID.
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/vci_offer_info_request'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/vci_offer_info_request'
responses:
'200':
description: Credential offer info retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/vci_offer_info_response'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'500':
$ref: '#/components/responses/500'
operationId: vci_offer_info_api
tags:
- Verifiable Credential Issuer
/api/{serviceId}/vci/single/parse:
post:
summary: Parse Single Credential
description: Parse a single verifiable credential
parameters:
- in: path
name: serviceId
description: A service ID.
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/vci_single_parse_request'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/vci_single_parse_request'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/vci_single_parse_response'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'500':
$ref: '#/components/responses/500'
operationId: vci_single_parse_api
tags:
- Verifiable Credential Issuer
/api/{serviceId}/vci/single/issue:
post:
summary: Issue Single Credential
description: Issue a single verifiable credential
parameters:
- in: path
name: serviceId
description: A service ID.
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/vci_single_issue_request'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/vci_single_issue_response'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'500':
$ref: '#/components/responses/500'
operationId: vci_single_issue_api
tags:
- Verifiable Credential Issuer
/api/{serviceId}/vci/batch/parse:
post:
summary: Parse Batch Credentials
description: Parse multiple verifiable credentials in batch
parameters:
- in: path
name: serviceId
description: A service ID.
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/vci_batch_parse_request'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/vci_batch_parse_request'
responses:
'200':
description: Batch credential parsing completed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/vci_batch_parse_response'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'500':
$ref: '#/components/responses/500'
operationId: vci_batch_parse_api
tags:
- Verifiable Credential Issuer
/api/{serviceId}/vci/batch/issue:
post:
summary: Issue Batch Credentials
description: Issue multiple verifiable credentials in batch
parameters:
- in: path
name: serviceId
description: A service ID.
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/vci_batch_issue_request'
responses:
'200':
description: Batch credential issuance completed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/vci_batch_issue_response'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'500':
$ref: '#/components/responses/500'
operationId: vci_batch_issue_api
tags:
- Verifiable Credential Issuer
/api/{serviceId}/vci/deferred/parse:
post:
summary: Parse Deferred Credential
description: Parse a deferred verifiable credential
parameters:
- in: path
name: serviceId
description: A service ID.
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/vci_deferred_parse_request'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/vci_deferred_parse_request'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/vci_deferred_parse_response'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'500':
$ref: '#/components/responses/500'
operationId: vci_deferred_parse_api
tags:
- Verifiable Credential Issuer
/api/{serviceId}/vci/deferred/issue:
post:
summary: Issue Deferred Credential
description: Issue a deferred verifiable credential
parameters:
- in: path
name: serviceId
description: A service ID.
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/vci_deferred_issue_request'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/vci_deferred_issue_response'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'500':
$ref: '#/components/responses/500'
operationId: vci_deferred_issue_api
tags:
- Verifiable Credential Issuer
components:
schemas:
vci_jwtissuer_response:
type: object
properties:
resultCode:
type: string
description: The code which represents the result of the API call.
resultMessage:
type: string
description: A short message which explains the result of the API call.
action:
type: string
enum:
- OK
- NOT_FOUND
- INTERNAL_SERVER_ERROR
description: 'The next action that the implementation of the JWT issuer metadata
endpoint (`/.well-known/jwt-issuer`) should take after getting
a response from Authlete''s `/vci/jwtissuer` API.
'
responseContent:
type: string
description: 'Get the content that the implementation of the credential issuer
metadata endpoint should use when it constructs a response.
'
vci_deferred_parse_request:
type: object
properties:
accessToken:
type: string
description: The access token that came along with the deferred credential request.
requestContent:
type: string
description: The message body of the deferred credential request.
vci_single_parse_response:
type: object
properties:
resultCode:
type: string
description: The code which represents the result of the API call.
resultMessage:
type: string
description: A short message which explains the result of the API call.
action:
type: string
enum:
- OK
- BAD_REQUEST
- UNAUTHORIZED
- FORBIDDEN
- INTERNAL_SERVER_ERROR
description: The next action that the credential endpoint should take.
responseContent:
type: string
description: The content of the response to the request sender.
info:
$ref: '#/components/schemas/credential_request_info'
vci_offer_info_request:
type: object
properties:
identifier:
type: string
description: The identifier of the credential offer.
vci_offer_create_request:
type: object
properties:
authorizationCodeGrantIncluded:
type: boolean
description: 'The flag indicating whether the `authorization_code` object is
included in the `grants` object.
'
issuerStateIncluded:
type: boolean
description: 'The flag indicating whether the `issuer_state` property is
included in the `authorization_code` object in the `grants`
object.
'
preAuthorizedCodeGrantIncluded:
type: boolean
description: 'The flag to include the
`urn:ietf:params:oauth:grant-type:pre-authorized_code` object
in the `grants` object.
'
subject:
type: string
description: The subject associated with the credential offer.
duration:
type: integer
format: int64
description: The duration of the credential offer.
context:
type: string
description: The general-purpose arbitrary string.
properties:
type: array
items:
$ref: '#/components/schemas/property'
description: Extra properties to associate with the credential offer.
jwtAtClaims:
type: string
description: 'Additional claims that are added to the payload part of the JWT
access token.
'
authTime:
type: integer
format: int64
description: 'The time at which the user authentication was performed during
the course of issuing the credential offer.
'
acr:
type: string
description: 'The Authentication Context Class Reference of the user authentication
performed during the course of issuing the credential offer.
'
credentialConfigurationIds:
type: array
items:
type: string
description: 'The value of the `credential_configuration_ids` array.
'
x-mint:
metadata:
description: The value of the `credential_configuration_ids` array.
content: "<Accordion title=\"Full description\" defaultOpen={false}>\n```\n{\n \"credential_issuer\": \"...\",\n \"credential_configuration_ids\": [ ... ],\n \"grants\": { ... }\n}\n```\n\nThis property is mandatory.\n</Accordion>\n"
txCode:
type: string
description: 'The transaction code that should be associated with the credential offer.
'
x-mint:
metadata:
description: The transaction code that should be associated with the credential offer.
content: "<Accordion title=\"Full description\" defaultOpen={false}>\nIf this parameter is not empty and the `preAuthorizedCodeGrantIncluded` parameter is `true`, the\n`urn:ietf:params:oauth:grant-type:pre-authorized_code` object will include the `tx_code` object.\n\nThe length of the value of this parameter will be used as the value of the `length` property in\nthe `tx_code` object.\n\n```\n{\n \"credential_issuer\": \"...\",\n \"credential_configuration_ids\": [ ... ],\n \"grants\": {\n \"urn:ietf:params:oauth:grant-type:pre-authorized_code\": {\n \"pre-authorized_code\": \"...\",\n \"tx_code\": {\n \"length\": length\n }\n }\n }\n}\n```\n</Accordion>\n"
txCodeInputMode:
type: string
description: 'The input mode of the transaction code.
'
x-mint:
metadata:
description: The input mode of the transaction code.
content: "<Accordion title=\"Full description\" defaultOpen={false}>\nThe value of this property will be used as the value of the `input_mode` property in the `tx_code`\nobject.\n\n```\n{\n \"credential_issuer\": \"...\",\n \"credential_configuration_ids\": [ ... ],\n \"grants\": {\n \"urn:ietf:params:oauth:grant-type:pre-authorized_code\": {\n \"pre-authorized_code\": \"...\",\n \"tx_code\": {\n \"length\": length,\n \"input_mode\": \"...\"\n }\n }\n }\n}\n```\n</Accordion>\n"
txCodeDescription:
type: string
description: 'The description of the transaction code.
'
x-mint:
metadata:
description: The description of the transaction code.
content: "<Accordion title=\"Full description\" defaultOpen={false}>\nThe value of this property will be used as the value of the `description` property in the `tx_code`\nobject.\n\n```\n{\n \"credential_issuer\": \"...\",\n \"credential_configuration_ids\": [ ... ],\n \"grants\": {\n \"urn:ietf:params:oauth:grant-type:pre-authorized_code\": {\n \"pre-authorized_code\": \"...\",\n \"tx_code\": {\n \"length\": length,\n \"description\": \"...\"\n }\n }\n }\n}\n```\n</Accordion>\n"
vci_offer_create_response:
type: object
properties:
resultCode:
type: string
description: The code which represents the result of the API call.
resultMessage:
type: string
description: A short message which explains the result of the API call.
action:
type: string
enum:
- CREATED
- FORBIDDEN
- CALLER_ERROR
- AUTHLETE_ERROR
description: The result of the `/vci/offer/create` API call.
info:
$ref: '#/components/schemas/credential_offer_info'
vci_deferred_parse_response:
type: object
properties:
resultCode:
type: string
description: The code which represents the result of the API call.
resultMessage:
type: string
description: A short message which explains the result of the API call.
action:
type: string
enum:
- OK
- BAD_REQUEST
- UNAUTHORIZED
- FORBIDDEN
- INTERNAL_SERVER_ERROR
description: The next action that the deferred credential endpoint should take.
responseContent:
type: string
description: The content of the response to the request sender.
info:
$ref: '#/components/schemas/credential_request_info'
description: Information about the credential request bound to the transaction ID.
vci_single_issue_response:
type: object
properties:
resultCode:
type: string
description: The code which represents the result of the API call.
resultMessage:
type: string
description: A short message which explains the result of the API call.
action:
type: string
enum:
- OK
- ACCEPTED
- UNAUTHORIZED
- FORBIDDEN
- INTERNAL_SERVER_ERROR
- CALLER_ERROR
description: 'The next action that the implementation of the credential endpoint
should take.
'
responseContent:
type: string
description: 'The content of the response that the implementation of the credential
endpoint should return.
'
transactionId:
type: string
description: 'The issued transaction ID.
'
vci_metadata_response:
type: object
properties:
resultCode:
type: string
description: The code which represents the result of the API call.
resultMessage:
type: string
description: A short message which explains the result of the API call.
action:
type: string
enum:
- OK
- NOT_FOUND
- INTERNAL_SERVER_ERROR
description: 'The next action that the implementation of the credential issuer
metadata endpoint (`/.well-known/openid-credential-issuer`)
should take after getting a response from Authlete''s
`/vci/metadata` API.
'
responseContent:
type: string
description: 'Get the content that the implementation of the credential issuer
metadata endpoint should use when it constructs a response.
'
property:
type: object
properties:
key:
type: string
description: The key part.
value:
type: string
description: The value part.
hidden:
type: boolean
description: 'The flag to indicate whether this property hidden from or visible to client applications.
If `true`, this property is hidden from client applications. Otherwise, this property is visible to client applications.
'
vci_jwks_request:
type: object
required:
- pretty
properties:
pretty:
type: boolean
description: 'The flag indicating whether the metadata is written in the pretty
format or not.
'
vci_single_parse_request:
type: object
properties:
accessToken:
type: string
description: The access token that came along with the credential request.
requestContent:
type: string
description: The message body of the credential request.
vci_metadata_request:
type: object
required:
- pretty
properties:
pretty:
type: boolean
description: 'The flag indicating whether the metadata is written in the pretty
format or not.
'
vci_deferred_issue_response:
type: object
properties:
resultCode:
type: string
description: The code which represents the result of the API call.
resultMessage:
type: string
description: A short message which explains the result of the API call.
action:
type: string
enum:
- OK
- FORBIDDEN
- INTERNAL_SERVER_ERROR
- CALLER_ERROR
description: 'The next action that the implementation of the deferred credential
endpoint should take.
'
responseContent:
type: string
description: 'The content of the response that the implementation of the deferred
credential endpoint should return.
'
vci_jwtissuer_request:
type: object
required:
- pretty
properties:
pretty:
type: boolean
description: 'The flag indicating whether the metadata is written in the pretty
format or not.
'
vci_batch_parse_request:
type: object
properties:
accessToken:
type: string
description: The access token that came along with the credential request.
requestContent:
type: string
description: The message body of the batch credential request.
vci_deferred_issue_request:
type: object
properties:
order:
$ref: '#/components/schemas/credential_issuance_order'
result:
type: object
properties:
resultCode:
type: string
description: The code which represents the result of the API call.
resultMessage:
type: string
description: A short message which explains the result of the API call.
vci_offer_info_response:
type: object
properties:
resultCode:
type: string
description: The code which represents the result of the API call.
resultMessage:
type: string
description: A short message which explains the result of the API call.
action:
type: string
enum:
- OK
- FORBIDDEN
- NOT_FOUND
- CALLER_ERROR
- AUTHLETE_ERROR
description: The result of the `/vci/offer/info` API call.
info:
$ref: '#/components/schemas/credential_offer_info'
vci_batch_issue_request:
type: object
properties:
accessToken:
type: string
description: The access token that came along with the credential request.
orders:
type: array
items:
$ref: '#/components/schemas/credential_issuance_order'
description: The instructions for issuance of credentials and/or transaction IDs.
credential_offer_info:
type: object
properties:
identifier:
type: string
description: The identifier of the credential offer.
credentialOffer:
type: string
description: The credential offer in the JSON format.
credentialIssuer:
type: string
description: The identifier of the credential issuer.
authorizationCodeGrantIncluded:
type: boolean
description: 'The flag indicating whether the `authorization_code` object is
included in the `grants` object.
'
issuerStateIncluded:
type: boolean
description: 'The flag indicating whether the `issuer_state` property is
included in the `authorization_code` object in the `grants`
object.
'
issuerState:
type: string
description: 'The value of the `issuer_state` property in the
`authorization_code` object in the `grants` object.
'
preAuthorizedCodeGrantIncluded:
type: boolean
description: 'The flag indicating whether the
`urn:ietf:params:oauth:grant-type:pre-authorized_code` object is
included in the `grants` object.
'
preAuthorizedCode:
type: string
description: 'The value of the `pre-authorized_code` property in the
`urn:ietf:params:oauth:grant-type:pre-author
# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/authlete/refs/heads/main/openapi/authlete-verifiable-credential-issuer-api-openapi.yml