openapi: 3.0.3 info: title: Authlete Authorization Endpoint Native SSO 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: Native SSO description: API endpoints for Native SSO x-tag-expanded: false paths: /api/{serviceId}/nativesso: post: summary: Native SSO Processing description: 'This API should be called by the implementation of a token endpoint to generate the ID token and token response that comply with [OpenID Connect Native SSO for Mobile Apps 1.0](https://openid.net/specs/openid-connect-native-sso-1_0.html) (Native SSO) when Authlete’s `/auth/token` response indicates `action = NATIVE_SSO` (after you validate the session id and verify or generate the device secret as required by the flow). The token endpoint implementation should retrieve the value of `action` from the response and take the following steps according to the value. ' x-mint: metadata: description: This API should be called by the implementation of a token endpoint to generate the ID token and token response that comply with [OpenID Connect Native SSO for Mobile Apps 1.0](https://openid.net/specs/openid-connect-native-sso-1_0.html) (Native SSO) when Authlete’s `/auth/token` response indicates `action = NATIVE_SSO` (after you validate the session id and verify or generate the device secret as required by the flow). The token endpoint implementation should retrieve the value of `action` from the response and take the following steps according to the value. content: ' ## OK When the action is `OK`, it indicates that the `/nativesso` API processing has successfully completed. In this case, the token endpoint implementation should return a successful response (`200 OK`) to the client. The value of the responseContent property in the `/nativesso` API response can be used directly as the message body of the token response. Therefore, the success response can be constructed as follows: ``` HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store (Embed the value of responseContent here.) ``` ## INTERNAL_SERVER_ERROR When the action is `INTERNAL_SERVER_ERROR`, it indicates that something has gone wrong on the Authlete side. For example, an issue such as a database error might have occurred when retrieving the access token specified by the accessToken parameter from the database. In such cases, the token endpoint implementation should return an error response to the client. The simplest implementation would be to return a `500 Internal Server Error`. ``` HTTP/1.1 500 Internal Server Error Content-Type: application/json Cache-Control: no-store (Embed the value of responseContent here.) ``` However, in a production environment, it may be better to return a more abstract error (one that does not directly describe the nature of the issue), rather than a `500` error. ## CALLER_ERROR When the action is `CALLER_ERROR`, it indicates that the issue lies with the caller of the API (i.e., the implementation of the OpenID Provider). For example, this could be due to missing a required parameter such as accessToken. If `CALLER_ERROR` is returned, please review the implementation of your OpenID Provider. ' parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string example: '715948317' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/native_sso_request' example: accessToken: _kh1aygxZ5NKLYKCJRM8M_AYvDg2wCWoprQDjfO87ZWq refreshToken: kHUGSt_d3LSgiCQzH7wa5TpwIHWgjAZGw14zZV7hRqw deviceSecret: my-ds claims: '{"given_name":"John","family_name":"Brown","email":"test@example.com"}' responses: '200': description: Native SSO processing completed successfully content: application/json: schema: $ref: '#/components/schemas/native_sso_response' example: resultCode: A501001 resultMessage: '[A501001] A Native SSO-compliant ID token and a token response were generated successfully.' action: OK responseContent: '{\"access_token\":\"_kh1aygxZ5NKLYKCJRM8M_AYvDg2wCWoprQDjfO87ZWq\",\"token_type\":\"Bearer\",\"expires_in\":86400,\"scope\":\"openid device_sso\",\"refresh_token\":\"kHUGSt_d3LSgiCQzH7wa5TpwIHWgjAZGw14zZV7hRqw\",\"id_token\":\"eyJraWQiOiItc1RSWDc5YnEyOEhyYkxBV0w2N3k4T1VJdXdrTms2ZFFkbzItSExZMkxvIiwiYWxnIjoiRVMyNTYifQ.eyJpc3MiOiJodHRwczovL2F1dGhsZXRlLmNvbSIsInN1YiI6ImpvaG4iLCJhdWQiOlsibmF0aXZlX2FwcF8xIl0sImV4cCI6MTc1NjcxNzY3MywiaWF0IjoxNzU2NzE3MzczLCJkc19oYXNoIjoic0luWlNhY1luRkR1Y1dwckRqZmtYeENRZl9mWGhsVDY1ZDduS0VYNzc2OCIsInNpZCI6Im15LXNpZCIsImdpdmVuX25hbWUiOiJKb2huIiwiZmFtaWx5X25hbWUiOiJCcm93biIsImVtYWlsIjoidGVzdEBleGFtcGxlLmNvbSJ9.RASuwd4KYPe8b3vNNwIYJgoXzUadDFFHO1wYWD70Z3EsZd8qcxxkPmJKs3dRitvYTX8DDqf5zvAm1jlIeEuvRQ\",\"device_secret\":\"my-ds\"}' idToken: eyJraWQiOiItc1RSWDc5YnEyOEhyYkxBV0w2N3k4T1VJdXdrTms2ZFFkbzItSExZMkxvIiwiYWxnIjoiRVMyNTYifQ.eyJpc3MiOiJodHRwczovL2F1dGhsZXRlLmNvbSIsInN1YiI6ImpvaG4iLCJhdWQiOlsibmF0aXZlX2FwcF8xIl0sImV4cCI6MTc1NjcxNzY3MywiaWF0IjoxNzU2NzE3MzczLCJkc19oYXNoIjoic0luWlNhY1luRkR1Y1dwckRqZmtYeENRZl9mWGhsVDY1ZDduS0VYNzc2OCIsInNpZCI6Im15LXNpZCIsImdpdmVuX25hbWUiOiJKb2huIiwiZmFtaWx5X25hbWUiOiJCcm93biIsImVtYWlsIjoidGVzdEBleGFtcGxlLmNvbSJ9.RASuwd4KYPe8b3vNNwIYJgoXzUadDFFHO1wYWD70Z3EsZd8qcxxkPmJKs3dRitvYTX8DDqf5zvAm1jlIeEuvRQ links: authz_process: $ref: '#/components/links/authz_process' token_exchange: $ref: '#/components/links/token_exchange' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: native_sso_api x-code-samples: - lang: shell label: curl source: 'curl -v -X POST https://us.authlete.com/api/21653835348762/nativesso \ -H ''Content-Type:application/json'' \ -H ''Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F'' \ -d ''{ "accessToken": "_kh1aygxZ5NKLYKCJRM8M_AYvDg2wCWoprQDjfO87ZWq", "refreshToken": "kHUGSt_d3LSgiCQzH7wa5TpwIHWgjAZGw14zZV7hRqw", "deviceSecret": "my-ds", "claims": "{\"given_name\":\"John\",\"family_name\":\"Brown\",\"email\":\"test@example.com\"}" }'' ' - lang: java label: java source: 'AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); NativeSsoRequest req = new NativeSsoRequest(); req.setAccessToken("_kh1aygxZ5NKLYKCJRM8M_AYvDg2wCWoprQDjfO87ZWq"); req.setRefreshToken("kHUGSt_d3LSgiCQzH7wa5TpwIHWgjAZGw14zZV7hRqw"); req.setDeviceSecret("my-ds"); req.setClaims("{\"given_name\":\"John\",\"family_name\":\"Brown\",\"email\":\"test@example.com\"}") api.nativeSso(req); ' tags: - Native SSO /api/{serviceId}/nativesso/logout: post: summary: Native SSO Logout Processing description: 'The `/nativesso/logout` API is supposed to be used to support the concept of "logout from all applications" in the context of [OpenID Connect Native SSO for Mobile Apps 1.0](https://openid.net/specs/openid-connect-native-sso-1_0.html) (Native SSO). This is accomplished by deleting access/refresh token records associated with the specified session ID. In Authlete''s implementation, access/refresh token records can be associated with a session ID only through the mechanism introduced by Native SSO. ' x-mint: metadata: description: The `/nativesso/logout` API is supposed to be used to support the concept of "logout from all applications" in the context of [OpenID Connect Native SSO for Mobile Apps 1.0](https://openid.net/specs/openid-connect-native-sso-1_0.html) (Native SSO). This is accomplished by deleting access/refresh token records associated with the specified session ID. In Authlete's implementation, access/refresh token records can be associated with a session ID only through the mechanism introduced by Native SSO. content: ' A response from the `/nativesso/logout` API contains `action` response parameter. The possible values are: ## OK When the action is `OK`, it indicates that the `/nativesso/logout` API call completed successfully. ## SERVER_ERROR When the action is `SERVER_ERROR`, it indicates that something has gone wrong on the Authlete side. ## CALLER_ERROR When the action is `CALLER_ERROR`, it indicates that the `/nativesso/logout` API call contained a problem. For example, the call may have been missing the required request parameter `sessionId`. ' parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/native_sso_logout_request' example: sessionId: my-sid responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/native_sso_logout_response' example: action: OK count: 2 resultCode: A503001 resultMessage: '[A503001] The /nativesso/logout API call successfully deleted 2 access/refresh token record(s).' links: authz_process: $ref: '#/components/links/authz_process' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: native_sso_logout_api x-code-samples: - lang: shell label: curl source: 'curl -v -X POST https://us.authlete.com/api/21653835348762/nativesso/logout \ -H ''Content-Type:application/json'' \ -H ''Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F'' \ -d ''{ "sessionId": "my-sid" }'' ' - lang: java label: java source: 'AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); NativeSsoLogoutRequest req = new NativeSsoLogoutRequest(); req.setSessionId("my-sid"); api.nativeSsoLogout(req); ' tags: - Native SSO components: schemas: native_sso_request: type: object required: - accessToken - deviceSecret properties: accessToken: type: string description: 'The value of this parameter should be: (a) the value of the `jwtAccessToken` parameter in a response from the `/auth/token` API when the value is available, or (b) the value of the `accessToken` parameter in the response from the `/auth/token` API when the `jwtAccessToken` parameter is not available. ' refreshToken: type: string description: 'The value of this parameter should be the value of the `refreshToken` parameter in a response from the `/auth/token` API. ' sub: type: string description: 'The value that should be used as the value of the `sub` claim of the ID token. This parameter is optional. When omitted, the value of the subject associated with the access token is used. ' claims: type: string description: 'Additional claims that should be embedded in the payload part of the ID token. The format is a JSON object. This parameter is optional. ' idtHeaderParams: type: string description: 'Additional parameters that should be embedded in the JWS header of the ID token. The format is a JSON object. This parameter is optional. ' idTokenAudType: type: string description: 'The type of the `aud` claim of the ID token being issued. Valid values of this parameter are as follows: ' x-mint: metadata: description: 'The type of the `aud` claim of the ID token being issued. Valid values of this parameter are as follows:' content: "\n- `\"array\"`\n The type of the `aud` claim becomes an array of strings.\n\n- `\"string\"`\n The type of the `aud` claim becomes a single string.\n\nThis parameter is optional, and the default value when omitted is `\"array\"`. This parameter takes\nprecedence over the `idTokenAudType` property of `Service`.\n\n" deviceSecret: type: string description: 'The device secret. The value of this parameter should be the value of the `deviceSecret` parameter in the response from the `/auth/token` API, if the parameter is present. Otherwise, the authorization server should generate a new device secret and specify it as the value of this parameter. ' x-mint: metadata: description: The device secret. The value of this parameter should be the value of the `deviceSecret` parameter in the response from the `/auth/token` API, if the parameter is present. Otherwise, the authorization server should generate a new device secret and specify it as the value of this parameter. content: ' The specified device secret is included as the value of the `device_secret` property in the token response prepared by the `/nativesso` API. Additionally, if the `deviceSecretHash` request parameter is omitted, the device secret is used to compute the value of the `ds_hash` claim. In this case, the `ds_hash` claim will be the base64url-encoded SHA-256 hash of the device secret. ' deviceSecretHash: type: string description: 'The device secret hash. The specified device secret hash is included as the value of the `ds_hash` claim in the ID token generated by the `/nativesso` API. If the `deviceSecretHash` request parameter is omitted, the value of the `deviceSecret` request parameter is used to compute the hash. ' native_sso_logout_request: type: object required: - sessionId properties: sessionId: type: string description: 'The session ID of a user''s authentication session. ' native_sso_logout_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 - SERVER_ERROR - CALLER_ERROR description: 'The next action that the API caller should take. ' count: type: integer description: 'The number of deleted access/refresh token records. ' native_sso_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 - INTERNAL_SERVER_ERROR - CALLER_ERROR description: 'The next action that the implementation of the token endpoint should take. ' responseContent: type: string description: 'The response content that can be used as the message body of the token response that should be returned from the token endpoint. ' idToken: type: string description: 'The issued ID token. ' 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. responses: '401': description: '' content: application/json: schema: $ref: '#/components/schemas/result' example: resultCode: A001202 resultMessage: '[A001202] /auth/authorization, Authorization header is missing.' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/result' example: resultCode: A001201 resultMessage: '[A001201] /auth/authorization, TLS must be used.' '403': description: '' content: application/json: schema: $ref: '#/components/schemas/result' example: resultCode: A001215 resultMessage: '[A001215] /auth/authorization, The client (ID = 26837717140341) is locked.' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/result' example: resultCode: A001101 resultMessage: '[A001101] /auth/authorization, Authlete Server error.' links: token_exchange: operationId: auth_token_api parameters: serviceId: $request.path.serviceId authz_process: operationId: auth_authorization_api parameters: serviceId: $request.path.serviceId securitySchemes: bearer: type: http scheme: bearer bearerFormat: JWT description: 'Authenticate every request with a **Service Access Token** or **Organization Token**. Set the token value in the `Authorization: Bearer ` header. **Service Access Token**: Scoped to a single service. Use when automating service-level configuration or runtime flows. **Organization Token**: Scoped to the organization; inherits permissions across services. Use for org-wide automation or when managing multiple services programmatically. Both token types are issued by the Authlete console or provisioning APIs. '