Authentication EndPoints

The VOLTTRON Web API requires the use of bearer tokens to access resources. These tokens are JSON Web Tokens (JWT) and are provided by the two /authenticate endpoints (POST and PUT). Two classes of token are provided to the user:

• Refresh Tokens:

  Refresh tokens are long-lived, and used can be used to obtain a new short-lived access token. Refresh tokens are obtained by providing a valid username and password to the POST /authenticate endpoint. The refresh token SHOULD be kept secure on the client side, and SHOULD NOT be provided to API call other than to PUT /authenticate.

• Access Tokens:

  An access token are short-lived tokens required to obtain resources or services provided by other API endpoints. The access token is obtained using the PUT /authenticate endpoint. For convenience, an inital access token is provided by the POST /authenticate endpoint as well, but as use the POST method requires sending credentials to the server, this should only be used on the first call, with PUT being used thereafter to obtain new access tokens until the refresh token has also expired.

Note

Authentication begins by obtaining a JWT bearer refresh token from the POST /authenticate endpoint. An initial access token is provided by this endpoint as well. Subsequent access tokens are then obtained by providing the refresh token to the PUT /authenticate endpoint without resending of credentials.

---

POST /authenticate

Provide authentication credentials to receive refresh token.

The user provides a username and password in the request body. If authentication succeeds, the endpoint will returna a JWT bearer refresh token with user’s claims. An initial access token is also returned. The refresh token can then be provided to PUT /authenticate to obtain new short-lived access tokens, as needed, without sending the username and password again until the refresh token expires.

Request:

• Content Type: application/json

• Body:

  {
      "username": "<username>",
      "password": "<password>"
  }
  

Response:

• With valid username and password: 200 OK

  • Content Type: application/json

  • Body:

    {
        "refresh_token": "<jwt_refresh_token>",
        "access_token": "<jwt_access_token>"
    }
    

• With invalid username and password: 401 Unauthorized

---

PUT /authenticate

Renew access token.

The user provides a valid refresh token (provided by POST /authenticate) in the Authorization header to obtain a fresh access token. A current access token MAY also be provided, as needed, in the request body to keep open any existing subscriptions. All subsequent requests to any endpoint should include the new token, and the old access token should be discarded.

Request:

• Content Type: application/json

• Authorization: BEARER <jwt_refresh_token>

• Body (optional):

  {
    "current_access_token": "<jwt_access_token>"
  }
  

Response:

• With valid refresh token: 200 OK

  • Content Type: application/json

  • Body:

    {
        "access_token": "<new_jwt_access_token>"
    }
    

• With invalid or mismatched username, password, or token:

  401 Unauthorized