OAuth server token (/oauth/token/)
URL: https://[server_name]/api/v1/oauth/token/
This endpoint is used to verify a user's identity and upon confirming that identity, issue a token that allows access to resources protected by the Bearer token. Tokens are issued per application and user, and you can configure applications in the GUI. As long as the access token expiry of the application is not zero, these tokens can expire and can be refreshed. This endpoint can also be used to refresh a previously issued token.
Supported fields
| Field | Display name | Type | Required | Other restrictions |
|---|---|---|---|---|
| username | User username | string | If grant_type is password | |
| password | User password | string | If grant_type is password | |
| realm | User realm | string | If grant_type is password, and user is not local | The default realm is the realm selected as the default under Authentication > Self-Service Portal > Access Control > Realms. If you are authenticating a user from the default realm, you do not need to specify a realm. |
| refresh_token | Token used to refresh access_token | string | If grant_type is refresh_token | |
| grant_type | OAuth grant type | string | Yes | |
| client_id | String ID of client or application | string | Yes | |
| client_secret | Hash client secret | string | If application client_type is 'confidential' | |
| challenge | The type of multi-factor authentication challenge | string | If responding to multi-factor authentication challenge with challenge response | Can be 'otp', 'radius', etc. Reuse the challenge you received from the token endpoint. |
| challenge_response | String code challenge response | string | If responding to challenge | |
| method | The method of challenge response | string | Yes | Required if responding with an OTP challenge |
| session | OAuth grant type | string | If responding with an OTP challenge with ftm-push method |
Allowed methods
| HTTP method | Resource URI | Action |
|---|---|---|
| POST | /api/v1/oauth/token/ | Get token, or refresh token. |
Response codes
In addition to the general codes defined in General API response codes, a POST request to this resource can also result in the following return codes:
| Code | Response content | Description |
|---|---|---|
| 200 OK | Valid credentials | |
| 401 Unauthorized | Invalid credentials, or user improperly configured | |
| 406 Not Acceptable | Challenge, method, status, and optional session | Initial credentials are valid, but the user requires more information. Send additional information. |
Example
Get token:
curl -k -v -X POST \
https://[FortiAuthenticator_IP]/api/v1/oauth/token/ \
-H 'Content-Type: application/json' \
-d '{
"username": "luser1",
"password": "12345678",
"client_id": "client_id",
"grant_type": "password"
}'
Response:
{
"access_token": "shrWNdu1xJRUgpcUi2bhYRX1Sl8pXe",
"expires_in": 0,
"message": "successfully authenticated",
"refresh_token": "tU85BMdOoV3pktSSiLaABJN7ySiADZ",
"scope": "read",
"status": "success",
"token_type": "Bearer"
}
Refresh a token:
curl -k -v -X POST \
https://[FortiAuthenticator_IP]/api/v1/oauth/token/ \
-H 'Content-Type: application/json' \
-d '{
"grant_type": "refresh_token",
"refresh_token": "tU85BMdOoV3pktSSiLaABJN7ySiADZ"
}'
Response:
{
"access_token": "fzMK69MdyA0vRJXh2CWnuHRcpuQrpL",
"expires_in": 0,
"message": "Token has been refreshed successfully",
"refresh_token": "UqCV1xEPSoq4vSLE0YgXAkF2zzMGO5",
"scope": "read",
"status": "success",
"token_type": "Bearer"
}
Get a token with FTM push:
curl -k -v -X POST \
https://[FortiAuthenticator_IP]/api/v1/oauth/token/ \
-H 'Content-Type: application/json' \
-d '{
"username": "luser1",
"password": "12345678",
"client_id": "client_id",
"grant_type": "password"
}'
Response:
{
"challenge": "otp",
"method": "ftm-push",
"session": "480dccc0f6bf4ed69ba484320ef92781",
"status": "pending"
}
Check for FTM-PUSH approval:
curl -k -v -X GET \
'https://[FortiAuthenticator_IP]/api/v1/pushpoll/?s=480dccc0f6bf4ed69ba484320ef92781' \
-H 'Content-Type: application/json' \
Response if status is 'pending':
{
"challenge": "otp",
"method": "ftm-push",
"session": "480dccc0f6bf4ed69ba484320ef92781",
"status": "pending"
}
Response if status is 'success' (The push request was approved):
{
"challenge": "otp",
"challenge_response": "3njPWHp6LgXtRwwXabEN",
"method": "ftm-push",
"session": "480dccc0f6bf4ed69ba484320ef92781",
"status": "success"
}
Use the successful push session code to get a token:
curl -k -v -X POST \
https://[FAC_IP]/api/v1/oauth/token/ \
-H 'Content-Type: application/json' \
-d '{
"username": "luser1",
"password": "12345678",
"client_id": "client_id",
"grant_type": "password",
"challenge": "otp",
"challenge_response": "3njPWHp6LgXtRwwXabEN",
"method": "ftm-push",
"session": "480dccc0f6bf4ed69ba484320ef92781"
}'
Response:
{
"access_token": "c1t2I989RnZCn7xFNsDGLtGShdeSL6",
"expires_in": 36000,
"refresh_token": "nP0Fq74huju4gDLCR5jXHSxerDAXD3",
"scope": "read",
"status": "success",
"token_type": "Bearer"
}