15.1.1.2. Authentication endpoints

This REST API is used to authenticate the users. A user needs to authenticate when he wants to use the API for administrative tasks like enrolling a token.

This API must not be confused with the validate API, which is used to check, if a OTP value is valid. See Validate endpoints.

Authentication of users and admins is tested in tests/test_api_roles.py

You need to authenticate for all administrative tasks. If you are not authenticated, the API returns a 401 response.

To authenticate you need to send a POST request to /auth containing username and password.

GET /auth/rights

This returns the rights of the logged in user.

Request Headers

• Authorization – The authorization token acquired by /auth request

POST /auth

This call verifies the credentials of the user and issues an authentication token, that is used for the later API calls. The authentication token has a validity, that is usually 1 hour.

JSON Parameters

• username – The username of the user who wants to authenticate to the API.

• password – The password/credentials of the user who wants to authenticate to the API.

• realm – The realm where the user will be searched.

Return

A json response with an authentication token, that needs to be used in any further request.

Status Codes

• 200 OK – in case of success

• 401 Unauthorized – if authentication fails

Example Authentication Request:

POST /auth HTTP/1.1
Host: example.com
Accept: application/json

username=admin
password=topsecret

Example Authentication Response:

HTTP/1.0 200 OK
Content-Length: 354
Content-Type: application/json

{
     "id": 1,
     "jsonrpc": "2.0",
     "result": {
         "status": true,
         "value": {
             "token": "eyJhbGciOiJIUz....jdpn9kIjuGRnGejmbFbM"
         }
     },
     "version": "privacyIDEA unknown"
}

Response for failed authentication:

HTTP/1.1 401 UNAUTHORIZED
Content-Type: application/json
Content-Length: 203

{
   "id": 1,
   "jsonrpc": "2.0",
   "result": {
     "error": {
       "code": -401,
       "message": "missing Authorization header"
     },
     "status": false
   },
   "version": "privacyIDEA unknown",
   "config": {
     "logout_time": 30
   }
}

Example Request:

Requests to privacyidea then should use this security token in the Authorization field in the header.

GET /users/ HTTP/1.1
Host: example.com
Accept: application/json
Authorization: eyJhbGciOiJIUz....jdpn9kIjuGRnGejmbFbM