Authlete Federation Endpoint API
API endpoints for implementing OpenID Federation using Authlete.
OpenAPI Specification
openapi: 3.0.3
info:
title: Authlete Authorization Endpoint Federation Endpoint 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: Federation Endpoint
description: API endpoints for implementing OpenID Federation using Authlete.
x-tag-expanded: false
paths:
/api/{serviceId}/federation/configuration:
post:
summary: Process Entity Configuration Request
description: 'This API gathers the federation configuration about a service.
The authorization server implementation should
retrieve the value of the `action`
response parameter from the API response and take the following steps
according to the value.
'
x-mint:
metadata:
description: This API gathers the federation configuration about a service. The authorization server implementation should retrieve the value of the `action` response parameter from the API response and take the following steps according to the value.
content: '<Accordion title="Full description" defaultOpen={false}>
### `OK`
When the value of the `action` response
parameter is `OK`, it means that Authlete
could prepare an entity configuration successfully.
In this case, the implementation of the entity configuration endpoint of the
authorization server should return an HTTP response to the client application
with the HTTP status code "`200 OK`" and the content type
"`application/entity-statement+jwt`". The message body (= an entity
configuration in the JWT format) of the response has been prepared by
Authlete''s `/federation/configuration` API and it is available as the
`responseContent` response parameter.
The implementation of the entity configuration endpoint can construct an
HTTP response by doing like below.
```
200 OK
Content-Type: application/entity-statement+jwt
(Other HTTP headers)
(the value of the responseContent response parameter)
```
### `NOT_FOUND`
When the value of the `action` response
parameter is `NOT_FOUND`, it means that
the service configuration has not enabled the feature of [OpenID Connect
Federation 1.0](https://openid.net/specs/openid-connect-federation-1_0.html) and so the client application should have not access the
entity configuration endpoint.
In this case, the implementation of the entity configuration endpoint of the
authorization server should return an HTTP response to the client application
with the HTTP status code "`404 Not Found`" and the content type
"`application/json`". The message body (= error information in the JSON
format) of the response has been prepared by Authlete''s
`/federation/configuration` API and it is available as the
`responseContent` response parameter.
The implementation of the entity configuration endpoint can construct an
HTTP response by doing like below.
```
404 Not Found
Content-Type: application/json
(Other HTTP headers)
(the value of the responseContent response parameter)
```
### `INTERNAL_SERVER_ERROR`
could prepare an entity configuration successfully.
In this case, the implementation of the entity configuration endpoint of the
authorization server should return an HTTP response to the client application
with the HTTP status code "`200 OK`" and the content type
"`application/entity-statement+jwt`". The message body (= an entity
configuration in the JWT format) of the response has been prepared by
Authlete''s `/federation/configuration` API and it is available as the
`responseContent` response parameter.
The implementation of the entity configuration endpoint can construct an
HTTP response by doing like below.
```
200 OK
Content-Type: application/entity-statement+jwt
(Other HTTP headers)
(the value of the responseContent response parameter)
```
</Accordion>
'
parameters:
- in: path
name: serviceId
description: A service ID.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
responses:
'200':
description: Federation configuration retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/federation_configuration_response'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'500':
$ref: '#/components/responses/500'
operationId: federation_configuration_api
x-code-samples:
- lang: shell
label: curl
source: 'curl -v https://us.authlete.com/api/21653835348762/federation/configuration \
-H ''Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F''
'
- lang: java
label: java
source: 'AuthleteConfiguration conf = ...;
AuthleteApi api = AuthleteApiFactory.create(conf);
api.getFederationConfiguration();
'
- lang: python
source: 'conf = ...
api = AuthleteApiImpl(conf)
api.getFederationConfiguration(True)
'
tags:
- Federation Endpoint
/api/{serviceId}/federation/registration:
post:
summary: Process Federation Registration Request
description: 'The Authlete API is for implementations of the **federation registration
endpoint** that accepts "explicit client registration". Its details are
defined in [OpenID Connect Federation 1.0](https://openid.net/specs/openid-connect-federation-1_0.html).
The endpoint accepts `POST` requests whose `Content-Type`
is either of the following.
1. `application/entity-statement+jwt`- `application/trust-chain+json`
When the `Content-Type` of a request is
`application/entity-statement+jwt`, the content of the request is
the entity configuration of a relying party that is to be registered.
In this case, the implementation of the federation registration endpoint
should call Authlete''s `/federation/registration` API with the
entity configuration set to the `entityConfiguration` request
parameter.
On the other hand, when the `Content-Type` of a request is
`application/trust-chain+json`, the content of the request is a
JSON array that contains entity statements in JWT format. The sequence
of the entity statements composes the trust chain of a relying party
that is to be registered. In this case, the implementation of the
federation registration endpoint should call Authlete''s
`/federation/registration` API with the trust chain set to the
`trustChain` request parameter.
'
parameters:
- in: path
name: serviceId
description: A service ID.
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/federation_registration_request'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/federation_registration_request'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/federation_registration_response'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'500':
$ref: '#/components/responses/500'
operationId: federation_registration_api
tags:
- Federation Endpoint
components:
schemas:
grant_type:
type: string
description: 'The grant type of the access token when the access token was created.
'
enum:
- AUTHORIZATION_CODE
- IMPLICIT
- PASSWORD
- CLIENT_CREDENTIALS
- REFRESH_TOKEN
- CIBA
- DEVICE_CODE
- TOKEN_EXCHANGE
- JWT_BEARER
- PRE_AUTHORIZED_CODE
client_registration_type:
type: string
description: "Values for the `client_registration_types` RP metadata and the\n `client_registration_types_supported` OP metadata that are defined in\n [OpenID Connect Federation 1.0](https://openid.net/specs/openid-connect-federation-1_0.html).\n"
enum:
- AUTOMATIC
- EXPLICIT
client_extension:
type: object
properties:
requestableScopes:
type: array
items:
type: string
description: 'The set of scopes that the client application is allowed to request. This paramter will be one
of the following.
'
x-mint:
metadata:
description: The set of scopes that the client application is allowed to request. This paramter will be one of the following.
content: "<Accordion title=\"Full description\" defaultOpen={false}>\n - `null`\n - an empty set\n - a set with at least one element\n\nWhen the value of this parameter is `null`, it means that the set of scopes that the client\napplication is allowed to request is the set of the scopes that the service supports. When the\nvalue of this parameter is an empty set, it means that the client application is not allowed to\nrequest any scopes. When the value of this parameter is a set with at least one element, it means\nthat the set is the set of scopes that the client application is allowed to request.\n</Accordion>\n"
requestableScopesEnabled:
type: boolean
description: 'The flag to indicate whether "Requestable Scopes per Client" is enabled or not. If `true`, you
can define the set of scopes which this client application can request. If `false`, this client
application can request any scope which is supported by the authorization server.
'
accessTokenDuration:
type: integer
format: int64
description: 'The value of the duration of access tokens per client in seconds. In normal cases, the value of
the service''s `accessTokenDuration` property is used as the duration of access tokens issued by
the service. However, if this `accessTokenDuration` property holds a non-zero positive number
and its value is less than the duration configured by the service, the value is used as the duration
of access tokens issued to the client application.
Note that the duration of access tokens can be controlled by the scope attribute `access_token.duration`,
too. Authlete chooses the minimum value among the candidates.
'
refreshTokenDuration:
type: integer
format: int64
description: 'The value of the duration of refresh tokens per client in seconds. In normal cases, the value
of the service''s `refreshTokenDuration` property is used as the duration of refresh tokens issued
by the service. However, if this `refreshTokenDuration` property holds a non-zero positive number
and its value is less than the duration configured by the service, the value is used as the duration
of refresh tokens issued to the client application.
Note that the duration of refresh tokens can be controlled by the scope attribute `refresh_token.duration`,
too. Authlete chooses the minimum value among the candidates.
'
idTokenDuration:
type: integer
format: int64
description: 'The value of the duration of ID tokens per client in seconds. In normal cases, the value
of the service''s `idTokenDuration` property is used as the duration of ID tokens issued
by the service. However, if this `idTokenDuration` property holds a non-zero positive number
and its value is less than the duration configured by the service, the value is used as the duration
of ID tokens issued to the client application.
Note that the duration of refresh tokens can be controlled by the scope attribute `id_token.duration`,
too. Authlete chooses the minimum value among the candidates.
'
tokenExchangePermitted:
type: boolean
description: 'Get the flag indicating whether the client is explicitly given a
permission to make token exchange requests ([RFC 8693][https://www.rfc-editor.org/rfc/rfc8693.html])
'
client:
type: object
additionalProperties: true
example:
number: 1140735077
serviceNumber: 715948317
clientName: My Test Client
clientId: '1140735077'
clientSecret: gXz97ISgLs4HuXwOZWch8GEmgL4YMvUJwu3er_kDVVGcA0UOhA9avLPbEmoeZdagi9yC_-tEiT2BdRyH9dbrQQ
clientType: PUBLIC
redirectUris:
- https://example.com/callback
responseTypes:
- CODE
grantTypes:
- AUTHORIZATION_CODE
properties:
number:
type: integer
format: int32
readOnly: true
description: 'The sequential number of the client. The value of this property is assigned by Authlete.
'
serviceNumber:
type: integer
format: int32
readOnly: true
description: 'The sequential number of the service of the client application. The value of this property is
assigned by Authlete.
'
clientName:
type: string
description: 'The name of the client application. This property corresponds to `client_name` in
[OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata).
'
clientNames:
type: array
items:
$ref: '#/components/schemas/tagged_value'
description: 'Client names with language tags. If the client application has different names for different
languages, this property can be used to register the names.
'
description:
type: string
description: The description about the client application.
descriptions:
type: array
items:
$ref: '#/components/schemas/tagged_value'
description: 'Descriptions about the client application with language tags. If the client application has different
descriptions for different languages, this property can be used to register the descriptions.
'
clientId:
type: integer
format: int64
readOnly: true
description: The client identifier used in Authlete API calls. The value of this property is assigned by Authlete.
clientSecret:
type: string
readOnly: true
description: 'The client secret. A random 512-bit value encoded by base64url (86 letters). The value of this
property is assigned by Authlete.
'
x-mint:
metadata:
description: The client secret. A random 512-bit value encoded by base64url (86 letters). The value of this property is assigned by Authlete.
content: '<Accordion title="Full description" defaultOpen={false}>
Note that Authlete issues a client secret even to a "public" client application, but the client
application should not use the client secret unless it changes its client type to "confidential".
That is, a public client application should behave as if it had not been issued a client secret.
To be specific, a token request from a public client of Authlete should not come along with a
client secret although [RFC 6749, 3.2.1. Client Authentication](https://datatracker.ietf.org/doc/html/rfc6749#section-3.2.1)
says as follows.
> Confidential clients or other clients issued client credentials MUST authenticate with the
authorization server as described in Section 2.3 when making requests to the token endpoint.
</Accordion>
'
clientIdAlias:
type: string
description: 'The value of the client''s `client_id` property used in OAuth and OpenID Connect calls. By
default, this is a string version of the `clientId` property.
'
clientIdAliasEnabled:
type: boolean
description: Deprecated. Always set to `true`.
clientType:
$ref: '#/components/schemas/client_type'
applicationType:
$ref: '#/components/schemas/application_type'
logoUri:
type: string
description: 'The URL pointing to the logo image of the client application.
This property corresponds to `logo_uri` in [OpenID Connect Dynamic Client Registration 1.0, 2.
Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata).
'
logoUris:
type: array
items:
$ref: '#/components/schemas/tagged_value'
description: 'Logo image URLs with language tags. If the client application has different logo images for
different languages, this property can be used to register URLs of the images.
'
contacts:
type: array
items:
type: string
description: 'An array of email addresses of people responsible for the client application.
This property corresponds to contacts in [OpenID Connect Dynamic Client Registration 1.0, 2. Client
Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata).
'
tlsClientCertificateBoundAccessTokens:
type: boolean
description: 'The flag to indicate whether this client use TLS client certificate bound access tokens.
'
dynamicallyRegistered:
type: boolean
readOnly: true
description: 'The flag to indicate whether this client has been registered dynamically.
For more details, see [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591).
'
softwareId:
type: string
description: 'The unique identifier string assigned by the client developer or software publisher used by
registration endpoints to identify the client software to be dynamically registered.
This property corresponds to the `software_id metadata` defined in [2. Client Metadata](https://datatracker.ietf.org/doc/html/rfc7591#section-2)
of [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591).
'
developer:
type: string
description: 'The unique identifier of the developer who created this client application.
'
softwareVersion:
type: string
description: 'The version identifier string for the client software identified by the software ID.
This property corresponds to the software_version metadata defined in [2. Client Metadata](https://datatracker.ietf.org/doc/html/rfc7591#section-2)
of [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591).
'
registrationAccessTokenHash:
type: string
description: 'The hash of the registration access token for this client.
'
createdAt:
type: integer
format: int64
readOnly: true
description: The time at which this client was created. The value is represented as milliseconds since the UNIX epoch (1970-01-01).
modifiedAt:
type: integer
format: int64
readOnly: true
description: The time at which this client was last modified. The value is represented as milliseconds since the UNIX epoch (1970-01-01).
grantTypes:
type: array
items:
$ref: '#/components/schemas/grant_type'
description: 'A string array of grant types which the client application declares that it will restrict itself to using.
This property corresponds to `grant_types` in [OpenID Connect Dynamic Client Registration 1.0,
2. Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata).
'
responseTypes:
type: array
items:
$ref: '#/components/schemas/response_type'
description: 'A string array of response types which the client application declares that it will restrict itself to using.
This property corresponds to `response_types` in [OpenID Connect Dynamic Client Registration 1.0,
2. Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata).
'
redirectUris:
type: array
items:
type: string
description: 'Redirect URIs that the client application uses to receive a response from the authorization endpoint.
Requirements for a redirect URI are as follows.
'
x-mint:
metadata:
description: Redirect URIs that the client application uses to receive a response from the authorization endpoint. Requirements for a redirect URI are as follows.
content: '<Accordion title="Full description" defaultOpen={false}>
**Requirements by RFC 6749** (From [RFC 6749, 3.1.2. Redirection Endpoint](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2))
- Must be an absolute URI.
- Must not have a fragment component.
**Requirements by OpenID Connect** (From "[OpenID Connect Dynamic Client Registration 1.0, 2.
Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata),
application_type")
- The scheme of the redirect URI used for Implicit Grant by a client application whose application
is `web` must be `https`. This is checked at runtime by Authlete.
- The hostname of the redirect URI used for Implicit Grant by a client application whose application
type is `web` must not be `localhost`. This is checked at runtime by Authlete.
- The scheme of the redirect URI used by a client application whose application type is `native`
must be either (1) a custom scheme or (2) `http`, which is allowed only when the hostname part
is `localhost`. This is checked at runtime by Authlete.
## Requirements by Authlete
- Must consist of printable ASCII letters only.
- Must not exceed 200 letters.
Note that Authlete allows the application type to be `null`. In other words, a client application
does not have to choose `web` or `native` as its application type.
If the application type is `null`, the requirements by OpenID Connect are not checked at runtime.
An authorization request from a client application which has not registered any redirect URI
fails unless at least all the following conditions are satisfied.
- The client type of the client application is `confidential`.
- The value of `response_type` request parameter is `code`.
- The authorization request has the `redirect_uri` request parameter.
- The value of `scope` request parameter does not contain `openid`.
RFC 6749 allows partial match of redirect URI under some conditions (see [RFC 6749, 3.1.2.2.
Registration Requirements](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2.2) for
details), but OpenID Connect requires exact match.
</Accordion>
'
authorizationSignAlg:
$ref: '#/components/schemas/jws_alg'
authorizationEncryptionAlg:
$ref: '#/components/schemas/jwe_alg'
authorizationEncryptionEnc:
$ref: '#/components/schemas/jwe_enc'
tokenAuthMethod:
$ref: '#/components/schemas/client_auth_method'
tokenAuthSignAlg:
$ref: '#/components/schemas/jws_alg'
selfSignedCertificateKeyId:
type: string
description: 'The key ID of a JWK containing a self-signed certificate of this client.
'
tlsClientAuthSubjectDn:
type: string
description: 'The string representation of the expected subject distinguished name of the certificate this
client will use in mutual TLS authentication.
See `tls_client_auth_subject_dn` in "Mutual TLS Profiles for OAuth Clients, 2.3. Dynamic Client
Registration" for details.
'
tlsClientAuthSanDns:
type: string
description: 'The string representation of the expected DNS subject alternative name of the certificate this
client will use in mutual TLS authentication.
See `tls_client_auth_san_dns` in "Mutual TLS Profiles for OAuth Clients, 2.3. Dynamic Client
Registration" for details.
'
tlsClientAuthSanUri:
type: string
description: 'The string representation of the expected URI subject alternative name of the certificate this
client will use in mutual TLS authentication.
See `tls_client_auth_san_uri` in "Mutual TLS Profiles for OAuth Clients, 2.3. Dynamic Client
Registration" for details.
'
tlsClientAuthSanIp:
type: string
description: 'The string representation of the expected IP address subject alternative name of the certificate
this client will use in mutual TLS authentication.
See `tls_client_auth_san_ip` in "Mutual TLS Profiles for OAuth Clients, 2.3. Dynamic Client
Registration" for details.
'
tlsClientAuthSanEmail:
type: string
description: 'The string representation of the expected email address subject alternative name of the certificate
this client will use in mutual TLS authentication.
See `tls_client_auth_san_email` in "Mutual TLS Profiles for OAuth Clients, 2.3. Dynamic Client
Registration" for details.
'
parRequired:
type: boolean
description: 'The flag to indicate whether this client is required to use the pushed authorization request endpoint.
This property corresponds to the `require_pushed_authorization_requests` client metadata defined
in "OAuth 2.0 Pushed Authorization Requests".
'
requestObjectRequired:
type: boolean
description: 'The flag to indicate whether authorization requests from this client are always required to
utilize a request object by using either `request` or `request_uri` request parameter.
If this flag is set to `true` and the service''s `traditionalRequestObjectProcessingApplied` is
set to `false`, authorization requests from this client are processed as if `require_signed_request_object`
client metadata of this client is `true`. The metadata is defined in "JAR (JWT Secured Authorization Request)".
'
requestSignAlg:
$ref: '#/components/schemas/jws_alg'
requestEncryptionAlg:
$ref: '#/components/schemas/jwe_alg'
requestEncryptionEnc:
$ref: '#/components/schemas/jwe_enc'
requestUris:
type: array
items:
type: string
description: 'An array of URLs each of which points to a request object.
Authlete requires that URLs used as values for `request_uri` request parameter be pre-registered.
This property is used for the pre-registration.
See [OpenID Connect Core 1.0, 6.2. Passing a Request Object by Reference](https://openid.net/specs/op
# --- truncated at 32 KB (68 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/authlete/refs/heads/main/openapi/authlete-federation-endpoint-api-openapi.yml