Getting Started

Our API accepts JWT access tokens that comply with the OAuth 2.0 protocol to authenticate requests.

You have two options that comply with the OAuth 2.0 protocol to obtain an access_token and we recommend choosing one based on your use case.

• OAuth 2.0 Password Grant Type

  • The password grant type is preferred when a trusted client application needs to obtain an access token on behalf of a specific user by directly using their username and password. This approach is suitable for first-party applications where users trust the client with their credentials, enabling access to user-specific resources with full user context.

• OAuth 2.0 Client Credentials Grant Type.

  • The client credentials grant type is ideal when an application needs to authenticate itself to access its own resources or perform operations that are not user-specific. Commonly used in server-to-server interactions, this method allows the application to act autonomously by obtaining an access token using only its client ID and secret, without involving any end-user.

Notes:

1. Refresh Tokens and Expiry Patterns: Access tokens are typically short-lived to minimize security risks if compromised, while refresh tokens are long-lived and allow clients to obtain new access tokens without re-authenticating the user. In the password grant type, refresh tokens are often issued to maintain user sessions seamlessly. In contrast, refresh tokens are usually not issued with the client credentials grant type because the client can obtain new access tokens using its credentials whenever needed. Additionally, access tokens obtained via the client credentials grant type may sometimes have longer expiration times since the client is a trusted application acting on its own behalf without user interaction; however, this can vary based on the authorization server's policies and security considerations.

2. Butlr Dashboard Authentication: For the Butlr Dashboard we use OAuth 2.0 Authorization Code Grant via Auth0 hosted redirect to remove Butlr from the password exchange flow.