Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Password Limited Flow

This authentication flow is used by clients which have no interactive user interface (a headless client). When making requests on behalf of other users, the Authorization Code Flow must be used instead.

This is an in-house extension of OAuth 2.1 which allows for logging in directly with user credentials. This is antithetical to the preferred authentication flow which allows this service to maintain strict custody of user credentials. It is based on an OAuth 2.0 specification called the Resource Owner Password Credentials Grant which was later deprecated in OAuth 2.0 and removed from OAuth 2.1 due to security concerns.

This service adds limits to this flow which mitigate these concerns:

  • the client MUST allow for fewer than three users,
  • users of the client MUST be pre-registered by contacting us; and
  • the client MUST be able to keep its client secret confidential.

This flow does bypass any two-factor authentication (2FA) which might be configured for the user. If this service starts supporting WebCrypto or WebAuthn in the future, this flow will not support using those credentials.

To use this flow the client requests a Password Limited Grant from /token. The access and refresh tokens will be returned in the response.

It falls on the client developer to secure not only the access and refresh tokens, but the client secret and user credentials as well.

See the documentation for the Password Limited Grant for other restrictions and considerations.

Sample Workflow

  1. Authenticate by calling /token with grant_type=password_limited.
    • The response will be an access token (600 second lifetime / repeated use) and refresh token (7 day lifetime/single use). Times given are defaults.
  2. Make requests with the access token for ~590 seconds (providing some buffer).
    • Allowing it to expire is fine if you want to just make requests until the endpoint tells you the token is expired.
  3. Call /token with grant_type=refresh_token
    • The response is a new access token (600 second lifetime / repeated use) and refresh token (7 day lifetime/single use). Times given are defaults.
  4. Repeat as necessary