Fortinet Document Library

Version:

Version:

Version:

Version:


Table of Contents

REST API Solution Guide

Download PDF
Copy Link

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"

}

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"

}