Fortinet black logo

REST API Solution Guide

Realm authentication (/realmauth/)

Realm authentication (/realmauth/)

URL: https://[server_name]/api/[api_version]/realmauth/

This end-point is used to validate local, LDAP and RADIUS user credentials based on realm.

Note

User lockout policy can be changed under Authentication > User Account Policies > Lockouts. The policy will be applied as configured.

Behavior of the API

  • Either password or token_code needs to be specified.
  • If both are specified, password will be validated first, then token_code.
  • If only one is specified (either password or token_code), only that credential will be validated.
  • If a user doesn't have two-factor authentication configured, validation for that user with any token_code will fail.
  • If a user is configured with only FortiToken authentication (password-based authentication is disabled), specifying any password will fail.
Note

Before being able to validate an email token or SMS token, a token code needs to be sent to the user first. Please refer to either /localusers, /ldapusers or /radiususers documentation on how to send the token code.

Supported fields

Field Display name Type Required Other restrictions
username Username string Yes
realm Realm string Yes
password Password string No
token_code Security token code string No Supported token authentication: FortiToken, FortiToken Cloud, email token, SMS token.

Allowed Methods

HTTP Method Resource URI Action
POST /api/v1/realmauth/ Validate user's credentials.

Response codes

In addition to the general codes defined in General API response codes, a POST request to this resource can result in the following return codes:

Code Response content Description
200 OK User is successfully authenticated.

202 OK

User authenticated and password change required.

401 Unauthorized User authentication failed Credential is incorrect.
401 Unauthorized Account is disabled User account is currently disabled.
401 Unauthorized No token configured User does not have token-based authentication configured.
401 Unauthorized Token is out of sync The security token requires synchronization.
404 Not Found User does not exist The given username does not exist in the system.

Realm authentication (/realmauth/)

URL: https://[server_name]/api/[api_version]/realmauth/

This end-point is used to validate local, LDAP and RADIUS user credentials based on realm.

Note

User lockout policy can be changed under Authentication > User Account Policies > Lockouts. The policy will be applied as configured.

Behavior of the API

  • Either password or token_code needs to be specified.
  • If both are specified, password will be validated first, then token_code.
  • If only one is specified (either password or token_code), only that credential will be validated.
  • If a user doesn't have two-factor authentication configured, validation for that user with any token_code will fail.
  • If a user is configured with only FortiToken authentication (password-based authentication is disabled), specifying any password will fail.
Note

Before being able to validate an email token or SMS token, a token code needs to be sent to the user first. Please refer to either /localusers, /ldapusers or /radiususers documentation on how to send the token code.

Supported fields

Field Display name Type Required Other restrictions
username Username string Yes
realm Realm string Yes
password Password string No
token_code Security token code string No Supported token authentication: FortiToken, FortiToken Cloud, email token, SMS token.

Allowed Methods

HTTP Method Resource URI Action
POST /api/v1/realmauth/ Validate user's credentials.

Response codes

In addition to the general codes defined in General API response codes, a POST request to this resource can result in the following return codes:

Code Response content Description
200 OK User is successfully authenticated.

202 OK

User authenticated and password change required.

401 Unauthorized User authentication failed Credential is incorrect.
401 Unauthorized Account is disabled User account is currently disabled.
401 Unauthorized No token configured User does not have token-based authentication configured.
401 Unauthorized Token is out of sync The security token requires synchronization.
404 Not Found User does not exist The given username does not exist in the system.