API-first OAuth 2.0 / OpenID Connect backend. Management APIs configure services and clients; Runtime APIs implement authorization, token, introspection, CIBA, device flow, federation, and verifiable-credential issuance. 82 paths / 86 operations, OpenAPI 3.0.16, Bearer-token auth.
openapi: 3.0.3
info:
title: Authlete API
description: |
Welcome to the **Authlete API documentation**. Authlete is an **API-first service** where every aspect of the
platform is configurable via API. This documentation will help you authenticate and integrate with Authlete to
build powerful OAuth 2.0 and OpenID Connect servers.
At a high level, the Authlete API is grouped into two categories:
- **Management APIs**: Enable you to manage services and clients.
- **Runtime APIs**: Allow you to build your own Authorization Servers or Verifiable Credential (VC) issuers.
## 🌐 API Servers
Authlete is a global service with clusters available in multiple regions across the world:
- 🇺🇸 **US**: `https://us.authlete.com`
- 🇯🇵 **Japan**: `https://jp.authlete.com`
- 🇪🇺 **Europe**: `https://eu.authlete.com`
- 🇧🇷 **Brazil**: `https://br.authlete.com`
Our customers can host their data in the region that best meets their requirements.
## 🔑 Authentication
All API endpoints are secured using **Bearer token authentication**. You must include an access token in every request:
```
Authorization: Bearer YOUR_ACCESS_TOKEN
```
### Getting Your Access Token
Authlete supports two types of access tokens:
**Service Access Token** - Scoped to a single service (authorization server instance)
1. Log in to [Authlete Console](https://console.authlete.com)
2. Navigate to your service → **Settings** → **Access Tokens**
3. Click **Create Token** and select permissions (e.g., `service.read`, `client.write`)
4. Copy the generated token
**Organization Token** - Scoped to your entire organization
1. Log in to [Authlete Console](https://console.authlete.com)
2. Navigate to **Organization Settings** → **Access Tokens**
3. Click **Create Token** and select org-level permissions
4. Copy the generated token
> ⚠️ **Important Note**: Tokens inherit the permissions of the account that creates them. Service tokens can only
> access their specific service, while organization tokens can access all services within your org.
### Token Security Best Practices
- **Never commit tokens to version control** - Store in environment variables or secure secret managers
- **Rotate regularly** - Generate new tokens periodically and revoke old ones
- **Scope appropriately** - Request only the permissions your application needs
- **Revoke unused tokens** - Delete tokens you're no longer using from the console
### Quick Test
Verify your token works with a simple API call:
```bash
curl -X GET https://us.authlete.com/api/service/get/list \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
## 🎓 Tutorials
If you're new to Authlete or want to see sample implementations, these resources will help you get started:
- [Getting Started with Authlete](https://www.authlete.com/developers/getting_started/)
- [From Sign-Up to the First API Request](https://www.authlete.com/developers/tutorial/signup/)
## 🛠 Contact Us
If you have any questions or need assistance, our team is here to help:
- [Contact Page](https://www.authlete.com/contact/)
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: Service Management
description: API endpoints for managing services, including creation, update, and deletion of services.
x-tag-expanded: false
- name: Client Management
description: API endpoints for managing OAuth clients, including creation, update, and deletion of clients.
x-tag-expanded: false
- name: Authorization Endpoint
description: API endpoints for implementing OAuth 2.0 Authorization Endpoint.
x-tag-expanded: false
- name: Pushed Authorization Endpoint
description: API endpoints for implementing OAuth 2.0 Pushed Authorization Requests (PAR).
x-tag-expanded: false
- name: Token Endpoint
description: API endpoints for implementing OAuth 2.0 Token Endpoint.
x-tag-expanded: false
- name: Token Operations
description: API endpoints for various token related operations, including creating, revoking and deleting access_tokens with specified scopes.
x-tag-expanded: false
- name: Introspection Endpoint
description: API endpoints for implementing OAuth 2.0 Introspection Endpoint.
x-tag-expanded: false
- name: Revocation Endpoint
description: API endpoint for implementing OAuth 2.0 Revocation Endpoint.
x-tag-expanded: false
- name: UserInfo Endpoint
description: API endpoints for implementing OpenID Connect UserInfo Endpoint.
x-tag-expanded: false
- name: JWK Set Endpoint
description: API endpoints for to generate JSON Web Key Set (JWKS) for a service.
x-tag-expanded: false
- name: Discovery Endpoint
description: API endpoints for implementing OpenID Connect Discovery.
x-tag-expanded: false
- name: Configuration Endpoint
description: API endpoint for accessing configuration settings for a service.
x-tag-expanded: false
- name: Dynamic Client Registration
description: API endpoints for implementing OAuth 2.0 Dynamic Client Registration.
x-tag-expanded: false
- name: CIBA
description: API endpoints for implementing Client-Initiated Backchannel Authentication (CIBA).
x-tag-expanded: false
- name: Grant Management Endpoint
description: API endpoint for implementing OAuth 2.0 grants, including grant management actions like updating and revoking grants.
x-tag-expanded: false
- name: Jose Object
description: API endpoints for JOSE objects.
x-tag-expanded: false
- name: Device Flow
description: API endpoints for implementing OAuth 2.0 Device Flow
x-tag-expanded: false
- name: Federation Endpoint
description: API endpoints for implementing OpenID Federation using Authlete.
x-tag-expanded: false
- name: Verifiable Credential Issuer
description: API endpoints for implementing and running a Verifiable Credential Issuer (VCI).
x-tag-expanded: false
- name: Hardware Security Key
description: API endpoints for managing hardware security keys (HSK).
x-tag-expanded: false
- name: Utility Endpoints
description: API endpoints for various utility operations.
x-tag-expanded: false
- name: Native SSO
description: API endpoints for Native SSO
x-tag-expanded: false
paths:
/api/{serviceId}/service/get:
get:
summary: Get Service
description: |
Get a service.
If the access token can only view or modify clients underneath this service, but does not
have access to view this service directly, a limited view of the service will be returned.
parameters:
- in: path
name: serviceId
description: A service ID.
schema:
type: string
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/service'
examples:
full:
summary: Example showing the full service object.
value:
accessTokenDuration: 3600
accessTokenType: Bearer
allowableClockSkew: 0
apiKey: 21653835348762
attributes:
- key: attribute1-key
value: attribute1-value
- key: attribute2-key
value: attribute2-value
authorizationEndpoint: https://my-service.example.com/authz
authorizationResponseDuration: 0
authorizationCodeDuration: 0
backchannelAuthReqIdDuration: 0
backchannelBindingMessageRequiredInFapi: false
backchannelPollingInterval: 0
backchannelUserCodeParameterSupported: false
claimShortcutRestrictive: false
clientIdAliasEnabled: true
clientsPerDeveloper: 0
createdAt: 1639373421000
dcrScopeUsedAsRequestable: false
deviceFlowCodeDuration: 0
deviceFlowPollingInterval: 0
directAuthorizationEndpointEnabled: false
directIntrospectionEndpointEnabled: false
directJwksEndpointEnabled: false
directRevocationEndpointEnabled: false
directTokenEndpointEnabled: false
directUserInfoEndpointEnabled: false
dynamicRegistrationSupported: false
errorDescriptionOmitted: false
errorUriOmitted: false
frontChannelRequestObjectEncryptionRequired: false
grantManagementActionRequired: false
hsmEnabled: false
idTokenDuration: 0
introspectionEndpoint: https://my-service.example.com/introspection
issSuppressed: false
issuer: https://my-service.example.com
metadata:
- key: clientCount
value: '1'
missingClientIdAllowed: false
modifiedAt: 1639373421000
mutualTlsValidatePkiCertChain: false
nbfOptional: false
number: 5041
parRequired: false
pkceRequired: true
pkceS256Required: false
pushedAuthReqDuration: 0
refreshTokenDuration: 3600
refreshTokenDurationKept: false
refreshTokenDurationReset: false
refreshTokenKept: false
requestObjectEncryptionAlgMatchRequired: false
requestObjectEncryptionEncMatchRequired: false
requestObjectRequired: false
revocationEndpoint: https://my-service.example.com/revocation
scopeRequired: false
serviceName: My service
serviceOwnerNumber: 2
singleAccessTokenPerSubject: false
supportedClaimTypes:
- NORMAL
supportedDisplays:
- PAGE
supportedGrantTypes:
- AUTHORIZATION_CODE
- REFRESH_TOKEN
supportedIntrospectionAuthMethods:
- CLIENT_SECRET_BASIC
supportedResponseTypes:
- CODE
supportedRevocationAuthMethods:
- CLIENT_SECRET_BASIC
supportedScopes:
- defaultEntry: false
description: A permission to read your history.
name: history.read
- defaultEntry: false
description: A permission to read your timeline.
name: timeline.read
supportedTokenAuthMethods:
- CLIENT_SECRET_BASIC
tlsClientCertificateBoundAccessTokens: false
tokenEndpoint: https://my-service.example.com/token
tokenExpirationLinked: false
traditionalRequestObjectProcessingApplied: false
unauthorizedOnClientConfigSupported: false
userCodeLength: 0
limited:
summary: Example showing the limited service object.
value:
apiKey: 21653835348762
description: This Service.
number: 5041
serviceName: My service
links:
service_get_list:
$ref: '#/components/links/service_get_list'
service_update:
$ref: '#/components/links/service_update'
service_delete:
$ref: '#/components/links/service_delete'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'500':
$ref: '#/components/responses/500'
operationId: service_get_api
x-code-samples:
- lang: shell
label: curl
source: |
curl -v https://us.authlete.com/api/21653835348762/service/get \
-H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F'
- lang: java
label: java
source: |
AuthleteConfiguration conf = ...;
AuthleteApi api = AuthleteApiFactory.create(conf);
long serviceId = ...;
api.getService(serviceId);
- lang: python
source: |
conf = ...
api = AuthleteApiImpl(conf)
serviceId = ...
api.getService(serviceId)
tags:
- Service Management
/api/service/get/list:
get:
summary: List Services
description: |
Get a list of services.
If the access token can only view or modify clients underneath a service, but does not
have access to view that service directly, a limited view of the service will be returned.
Otherwise, all properties of the service are returned.
If the access token is an administrative token, this returns a list of all services on the Authlete instance.
Otherwise, all services that the access token can view, even in a limited fashion, are returned.
parameters:
- in: query
name: start
schema:
type: integer
format: int32
required: false
description: Start index (inclusive) of the result set. The default value is 0. Must not be a negative number.
- in: query
name: end
schema:
type: integer
format: int32
required: false
description: End index (exclusive) of the result set. The default value is 5. Must not be a negative number.
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/service_get_list_response'
examples:
full:
summary: Example showing the full service view.
value:
start: 0
end: 5
totalCount: 1
services:
- accessTokenDuration: 3600
accessTokenType: Bearer
allowableClockSkew: 0
apiKey: 21653835348762
apiSecret: uE4NgqeIpuSV_XejQ7Ds3jsgA1yXhjR1MXJ1LbPuyls
attributes:
- key: attribute1-key
value: attribute1-value
- key: attribute2-key
value: attribute2-value
authorizationEndpoint: https://as.example.com/authz
authorizationResponseDuration: 0
authorizationCodeDuration: 0
backchannelAuthReqIdDuration: 0
backchannelBindingMessageRequiredInFapi: false
backchannelPollingInterval: 0
backchannelUserCodeParameterSupported: false
claimShortcutRestrictive: false
clientIdAliasEnabled: true
createdAt: 1639373421000
dcrScopeUsedAsRequestable: false
deviceFlowCodeDuration: 0
deviceFlowPollingInterval: 0
directAuthorizationEndpointEnabled: false
directIntrospectionEndpointEnabled: false
directJwksEndpointEnabled: false
directRevocationEndpointEnabled: false
directTokenEndpointEnabled: false
directUserInfoEndpointEnabled: false
dynamicRegistrationSupported: false
errorDescriptionOmitted: false
errorUriOmitted: false
frontChannelRequestObjectEncryptionRequired: false
grantManagementActionRequired: false
hsmEnabled: false
idTokenDuration: 0
introspectionEndpoint: https://my-service.example.com/introspection
issSuppressed: false
issuer: https://my-service.example.com
metadata:
- key: clientCount
value: '1'
missingClientIdAllowed: false
modifiedAt: 1639373421000
mutualTlsValidatePkiCertChain: false
nbfOptional: false
number: 5041
parRequired: false
pkceRequired: true
pkceS256Required: false
pushedAuthReqDuration: 0
refreshTokenDuration: 3600
refreshTokenDurationKept: false
refreshTokenDurationReset: false
refreshTokenKept: false
requestObjectEncryptionAlgMatchRequired: false
requestObjectEncryptionEncMatchRequired: false
requestObjectRequired: false
revocationEndpoint: https://my-service.example.com/revocation
scopeRequired: false
serviceName: My service
serviceOwnerNumber: 2
singleAccessTokenPerSubject: false
supportedClaimTypes:
- NORMAL
supportedDisplays:
- PAGE
supportedGrantTypes:
- AUTHORIZATION_CODE
- REFRESH_TOKEN
supportedIntrospectionAuthMethods:
- CLIENT_SECRET_BASIC
supportedResponseTypes:
- CODE
supportedRevocationAuthMethods:
- CLIENT_SECRET_BASIC
supportedScopes:
- defaultEntry: false
description: A permission to read your history.
name: history.read
- defaultEntry: false
description: A permission to read your timeline.
name: timeline.read
supportedTokenAuthMethods:
- CLIENT_SECRET_BASIC
tlsClientCertificateBoundAccessTokens: false
tokenEndpoint: https://my-service.example.com/token
tokenExpirationLinked: false
traditionalRequestObjectProcessingApplied: false
unauthorizedOnClientConfigSupported: false
userCodeLength: 0
limited:
summary: Example showing the limited service view.
value:
start: 0
end: 5
totalCount: 1
services:
- apiKey: 21653835348762
clientIdAliasEnabled: true
number: 5041
serviceName: My service
links:
service_create:
$ref: '#/components/links/service_create'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'500':
$ref: '#/components/responses/500'
operationId: service_get_list_api
x-code-samples:
- lang: shell
label: curl
source: |
curl -v https://us.authlete.com/api/9503564192/service/get/list?start=0\&end=5 \
-H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F'
- lang: java
label: java
source: |
AuthleteConfiguration conf = ...;
AuthleteApi api = AuthleteApiFactory.create(conf);
int start = 0;
int end = 5;
api.getServiceList(start, end);
- lang: python
source: |
conf = ...
api = AuthleteApiImpl(conf)
start = 0
end = 5
api.getServiceList(start, end)
tags:
- Service Management
/api/service/create:
post:
summary: Create Service
description: |
Create a new service.
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/service'
example:
serviceName: My service
issuer: https://my-service.example.com
clientIdAliasEnabled: true
supportedGrantTypes:
- AUTHORIZATION_CODE
- REFRESH_TOKEN
supportedResponseTypes:
- CODE
authorizationEndpoint: https://my-service.example.com/authz
pkceRequired: true
tokenEndpoint: https://my-service.example.com/token
supportedTokenAuthMethods:
- CLIENT_SECRET_BASIC
revocationEndpoint: https://my-service.example.com/revocation
supportedRevocationAuthMethods:
- CLIENT_SECRET_BASIC
introspectionEndpoint: https://my-service.example.com/introspection
supportedIntrospectionAuthMethods:
- CLIENT_SECRET_BASIC
accessTokenType: Bearer
accessTokenDuration: 3600
refreshTokenDuration: 3600
supportedScopes:
- name: timeline.read
defaultEntry: false
description: A permission to read your timeline.
- name: history.read
defaultEntry: false
description: A permission to read your history.
attributes:
- key: attribute1-key
value: attribute1-value
- key: attribute2-key
value: attribute2-value
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/service'
responses:
'200':
description: Service created successfully (legacy compatibility)
content:
application/json:
schema:
$ref: '#/components/schemas/service'
example:
accessTokenDuration: 3600
'201':
description: Service created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/service'
example:
accessTokenDuration: 3600
accessTokenType: Bearer
allowableClockSkew: 0
apiKey: 21653835348762
apiSecret: uE4NgqeIpuSV_XejQ7Ds3jsgA1yXhjR1MXJ1LbPuyls
attributes:
- key: attribute1-key
value: attribute1-value
- key: attribute2-key
value: attribute2-value
authorizationEndpoint: https://my-service.example.com/authz
authorizationResponseDuration: 0
authorizationCodeDuration: 0
backchannelAuthReqIdDuration: 0
backchannelBindingMessageRequiredInFapi: false
backchannelPollingInterval: 0
backchannelUserCodeParameterSupported: false
claimShortcutRestrictive: false
clientIdAliasEnabled: true
clientsPerDeveloper: 0
createdAt: 1639373421000
dcrScopeUsedAsRequestable: false
deviceFlowCodeDuration: 0
deviceFlowPollingInterval: 0
directAuthorizationEndpointEnabled: false
directIntrospectionEndpointEnabled: false
directJwksEndpointEnabled: false
directRevocationEndpointEnabled: false
directTokenEndpointEnabled: false
directUserInfoEndpointEnabled: false
dynamicRegistrationSupported: false
errorDescriptionOmitted: false
errorUriOmitted: false
frontChannelRequestObjectEncryptionRequired: false
grantManagementActionRequired: false
hsmEnabled: false
idTokenDuration: 0
introspectionEndpoint: https://my-service.example.com/introspection
issSuppressed: false
issuer: https://my-service.example.com
metadata:
- key: clientCount
value: '0'
missingClientIdAllowed: false
modifiedAt: 1639373421000
mutualTlsValidatePkiCertChain: false
nbfOptional: false
number: 5041
parRequired: false
pkceRequired: true
pkceS256Required: false
pushedAuthReqDuration: 0
refreshTokenDuration: 3600
refreshTokenDurationKept: false
refreshTokenDurationReset: false
refreshTokenKept: false
requestObjectEncryptionAlgMatchRequired: false
requestObjectEncryptionEncMatchRequired: false
requestObjectRequired: false
revocationEndpoint: https://my-service.example.com/revocation
scopeRequired: false
serviceName: My service
serviceOwnerNumber: 2
singleAccessTokenPerSubject: false
supportedClaimTypes:
- NORMAL
supportedDisplays:
- PAGE
supportedGrantTypes:
- AUTHORIZATION_CODE
- REFRESH_TOKEN
supportedIntrospectionAuthMethods:
- CLIENT_SECRET_BASIC
supportedResponseTypes:
- CODE
supportedRevocationAuthMethods:
- CLIENT_SECRET_BASIC
supportedScopes:
- defaultEntry: false
description: A permission to read your history.
name: history.read
- defaultEntry: false
description: A permission to read your timeline.
name: timeline.read
supportedTokenAuthMethods:
- CLIENT_SECRET_BASIC
tlsClientCertificateBoundAccessTokens: false
tokenEndpoint: https://my-service.example.com/token
tokenExpirationLinked: false
traditionalRequestObjectProcessingApplied: false
unauthorizedOnClientConfigSupported: false
userCodeLength: 0
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'500':
$ref: '#/components/responses/500'
operationId: service_create_api
x-code-samples:
- lang: shell
label: curl
source: |
curl -v -X POST https://us.authlete.com/api/service/create \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \
-d '{ "serviceName": "My Service", ... }'
- lang: java
label: java
source: |
AuthleteConfiguration conf = ...;
AuthleteApi api = AuthleteApiFactory.create(conf);
Service service = new Service();
service.setServiceName("My Service");
...
api.createService(service);
- lang: python
source: |
conf = ...
api = AuthleteApiImpl(conf)
service = Service()
service.serviceName = 'My Service'
...
api.createService(service)
tags:
- Service Management
/api/{serviceId}/service/update:
post:
summary: Update Service
description: |
Update a service.
parameters:
- in: path
name: serviceId
description: A service ID.
schema:
type: string
required: true
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/service'
example:
accessTokenDuration: 3600
accessTokenType: Bearer
allowableClockSkew: 0
attributes:
- key: attribute1-key
value: attribute1-value
- key: attribute2-key
value: attribute2-value
authorizationEndpoint: https://my-service.example.com/authz
authorizationResponseDuration: 0
authorizationCodeDuration: 0
backchannelAuthReqIdDuration: 0
backchannelBindingMessageRequiredInFapi: false
backchannelPollingInterval: 0
backchannelUserCodeParameterSupported: false
claimShortcutRestrictive: false
clientIdAliasEnabled: true
clientsPerDeveloper: 0
dcrScopeUsedAsRequestable: false
deviceFlowCodeDuration: 0
deviceFlowPollingInterval: 0
directAuthorizationEndpointEnabled: false
directIntrospectionEndpointEnabled: false
directJwksEndpointEnabled: false
directRevocationEndpointEnabled: false
directTokenEndpointEnabled: false
directUserInfoEndpointEnabled: false
dynamicRegistrationSupported: false
errorDescriptionOmitted: false
errorUriOmitted: false
frontChannelRequestObjectEncryptionRequired: false
grantManagementActionRequired: false
hsmEnabled: false
idTokenDuration: 0
introspectionEndpoint: https://my-service.example.com/introspection
issSuppressed: false
issuer: https://my-service.example.com
missingClientIdAllowed: false
mutualTlsValidatePkiCertChain: false
nbfOptional: false
parRequired: false
pkceRequired: true
pkceS256Required: false
pushedAuthReqDuration: 0
refreshTokenDuration: 3600
refreshTokenDurationKept: false
refreshTokenDurationReset: false
refreshTokenKept: false
requestObjectEncryptionAlgMatchRequired: false
requestObjectEncryptionEncMatchRequired: false
requestObjectRequired: false
revocationEndpoint: https://my-service.example.com/revocation
scopeRequired: false
serviceName: My updated service
singleAccessTokenPerSubject: false
supportedClaimTypes:
- NORMAL
supportedDisplays:
- PAGE
supp
# --- truncated at 32 KB (865 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/authlete/refs/heads/main/openapi/authlete-openapi-original.yml