Authentication

Authentication throughout HumanFirst is handled by Google's identity platform. Here is a summary on the procedure to follow in order to acquire the right tokens to make API requests.

tip

If you use our command line tool, the command hf auth print-access-token will output a valid token to stdout while automatically refreshing it, if required.

Initial authentication#

The authentication process takes in credentials and yields an access token and a refresh token. The access tokens have a lifetime of 1 hour, after which they must be refreshed in order to keep calling the API.

A POST request must be sent to https://identitytoolkit.googleapis.com/v1/accounts:signInWithPassword?key=AIzaSyA5xZ7WCkI6X1Q2yzWHUrc70OXH5iCp7-c with the following headers:

Header	Value
Content-Type	application/json; charset=utf-8

{
    "email": "[email protected]",
    "password": "plaintext user password",
    "returnSecureToken": true
}

A successful response will be similar to the following object.

{
  "kind": "identitytoolkit#VerifyPasswordResponse",
  "localId": "userid",
  "email": "[email protected]",
  "displayName": "",
  "idToken": "eyJh...",
  "registered": true,
  "refreshToken": "...",
  "expiresIn": "3600"
}

The idToken can be used immediately, while the refreshToken should be kept in a safe location, as it will be used to obtain further tokens.

info

For brievity, only the successful case is shown here. For more information please visit the relevant Google identity platform documentation

Refreshing tokens#

After the token expires (denoted by the expiresIn field in the previous response, which is usually set to 1h (3600 seconds)) - it must be refreshed in order to obtain a new valid token.

A POST request must be sent to https://securetoken.googleapis.com/v1/token?key=AIzaSyA5xZ7WCkI6X1Q2yzWHUrc70OXH5iCp7-c with the following headers:

Header	Value
Content-Type	application/json; charset=utf-8

And the payload:

{
  "refresh_token": "refresh token from last login",
  "grant_type": "refresh_token"
}

A successful response:

{
  "access_token": "eyJh...",
  "expires_in": "3600",
  "token_type": "Bearer",
  "refresh_token": "...",
  "id_token": "eyJh...",
  "user_id": "userid",
  "project_id": "79221509215"
}

info

For brievity, only the successful case is shown here. For more information please visit the relevant Google identity platform documentation

warning

Refresh tokens will be invalidated if the user changes the associated password. Changing password is a good way to invalidate any active sessions (either browser or API)

Making requests#

Each call must be authenticated using the HTTP Authorization field, where the token is prefixed by Bearer as defined in RFC6750 Section 2.1.

Example:

POST /... HTTP/1.1
Authorization: Bearer eyJh....