> ## Documentation Index
> Fetch the complete documentation index at: https://developers.authlete.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Developer Authentication Callback
> このドキュメントでは、開発者認証コールバックエンドポイントの実装について解説しています。Authlete が提供する開発者コンソールをサードパーティアプリ開発者に公開する場合、このエンドポイントの実装が必要となります。
This document describes how to implement your **developer authentication callback endpoint**.
# 1. Target Readers
You need to implement your developer authentication callback endpoint (and so have to read this document) only if you want to let (third-party) developers use **Developer Console**.
**Need to Read?**
As a special behavior, the login form of Developer Console accepts the pair of API key & API secret of the corresponding service as if it were a valid pair of ID & password of a developer. Therefore, if you are the only person who manages client applications for your service, you don't have to implement a developer authentication callback endpoint. In this case, you don't have to read this document.
Authlete provides Web APIs to manage client applications such as `/client/create`. Using such [Authlete Web APIs](https://docs.authlete.com), you can build your own tools to manage client applications. If you do it, you don't have to use Developer Console and so you don't have to implement a developer authentication callback.
# 2. What is "Developer Authentication Callback Endpoint"?
Developer authentication callback is a Web API that you are required to implement to authenticate developers. Authlete calls the Web API when developer authentication is needed.
# 3. Why Is Developer Authentication Callback Endpoint Needed?
Since Authlete does NOT have any database table to manage developer accounts, Authlete cannot perform developer authentication. This is by design. Therefore, Authlete delegates developer authentication to your developer authentication callback endpoint.
# 4. Settings
Authlete needs to know the location of your developer authentication callback endpoint, so it is required to set necessary information via [Service Owner Console](https://so.authlete.com/). Please follow the steps below.
1. Login [Service Owner Console](https://so.authlete.com/), and you will see the list of your services.
2. Click Edit button of a service for which you are going to provide a developer authentication callback endpoint.
3. Click "Developer Authentication" tab and you will find "Callback" at the top.
4. Input values for the configuration parameters properly.
5. Click "Update" button to save the changes.
| parameters | description |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Developer Authentication Callback Endpoint | The URL of your developer authentication callback endpoint. The location must be accessible from Authlete server. The URL should start `https://` for security. |
| Developer Authentication Callback API Key & Secret | If these values are not empty, Authlete uses the values to add `Authorization` header for Basic Authentication when calling your developer authentication callback endpoint. You can ensure that developer authentication requests have come from Authlete by checking the API credentials. |
# 5. Developer Authentication Callback Request
A request from Authlete to a developer authentication callback endpoint follows the specification described below.
## HTTP method
`POST` method
## Content-Type
`application/json`
## Basic Authentication
If you set non-empty values to "Developer Authentication Callback API Key" and "Developer Authentication Callback API Secret" of the service using [Service Owner Console](https://so.authlete.com/), requests from Authlete contain `Authorization` header for Basic Authentication.
## Data Format
The entity body of a developer authentication callback request is JSON. The JSON contains the properties listed in the table below ([DeveloperAuthenticationCallbackRequest.java](https://github.com/authlete/authlete-java-common/blob/master/src/main/java/com/authlete/common/dto/DeveloperAuthenticationCallbackRequest.java) in [authlete-java-common](https://github.com/authlete/authlete-java-common) is always the latest format).
Probably, the number of properties is much larger than you guessed. However, if you don't have a mind to support social login at the login form of Developer Console, properties you have to care about are just `id` and `password`. (Social login for Developer Console is not supported yet.)
| Property | Description |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `serviceApiKey` | The API key of your service. |
| `id` | When sns property is null, id is the value that the developer input to the "Login ID" field in the login form of Developer Console.
Otherwise, when sns property is not null, id is the value of the subject (= unique identifier) of the developer in the SNS. |
| `password` | When sns property is null, password is the value that the developer input to the "Password" field in the login form of Developer Console.
Otherwise, when sns property is not null, password has no meaning. |
| `sns` | When the developer performed social login at the login page, sns property holds the name of the SNS such as FACEBOOK.
sns property is always null unless you enable social login support in "Developer Authentication" tab. |
| `accessToken` | When the developer performed social login at the login page, accessToken property holds the access token which was issued from the token endpoint of the SNS. |
| `refreshToken` | When the developer performed social login at the login page, refreshToken property holds the refresh token which was issued from the token endpoint of the SNS. If the SNS has not issued a refresh token, this property is null. |
| `expiresIn` | When the developer performed social login at the login page, expiresIn property holds the duration of the access token in seconds. If the SNS has not returned information about the duration, this property is 0. |
| `rawTokenResponse` | When the developer performed social login at the login page, rawTokenResponse property holds the content of the response from the token endpoint of the SNS.
Correct implementations of token endpoints return application/json, so the content of rawTokenResponse property is formatted in JSON. However, note that the token endpoint of Facebook returns data in the format of application/x-www-url-encoded. This is a violation against RFC 6749 (OAuth 2.0). |
# 6. Developer Authentication Callback Response
A developer authentication callback endpoint is required to return a response that complies with the requirements described below.
## Content-Type
`application/json; charset=UTF-8`
## Recommended HTTP headers
`Cache-Control: no-store`
`Pragma: no-cache`
## Data Format
The entity body of a developer authentication callback response must be JSON. The properties expected to be contained in the JSON are listed in the table below ([DeveloperAuthenticationCallbackResponse.java](https://github.com/authlete/authlete-java-common/blob/master/src/main/java/com/authlete/common/dto/DeveloperAuthenticationCallbackResponse.java) in [authlete-java-common](https://github.com/authlete/authlete-java-common) is always the latest format).
| Property | Description |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `authenticated` | The result of authentication. Set `true` when the developer was authenticated successfully. |
| `subject` | The unique identifier of the developer in your service. It must consist of only printable ASCII letters and its length must not exceed 100.
Note that the value of `subject` property in the response does not have to be equal to the value of `id` property in the request. For example, if your service can identify a developer by an email address, your service may look up a developer by an email address when the given `id` looks like an email address. In such a case, the value of `subject` property in the response is different from `id` property in the request (unless your system uses email addresses as subjects of developers).
When `authenticated` property is `false`, `subject` property may be null. |
| `displayName` | The display name of the developer. May be null. Its length must not exceed 100. |
# 7. Sample Implementation
TBW