Skip to content

Bearer Tokens & Access Control

As mentioned in the API Configuration topic, when enable_auth is set as true, Atlas automatically enables both the API Gateway Authorizer and the auth_tokens DynamoDB table.

This topic will show how to properly interact with the auth_tokens table and describes the behavior of the Authorizer.

auth_tokens

auth_tokens is a DynamoDB table automatically created and linked to your API when enable_auth is set to true. Each item in this table follows the structure below:

  • token: Primary index. A random string validated by the Authorizer. It serves as a bearer token used for authorizing requests to non-public endpoints via the Authorization header.

  • expires_at: The token's time to live (in seconds). DynamoDB automatically deletes the token when it expires.

  • sub: A global secondary index representing the “subject,” similar to its use in JWTs. It can store any string, but it’s typically used to store the authenticated user’s id.

  • role: A global secondary index that can hold any string, typically used to represent the permission group name associated with the user.

  • permissions: Defines the endpoints accessible by this token. It must follow the format: HTTPMETHOD_OR_ALL endpoint_route, separated by a comma and a space. Example: "GET /users/*, POST /orders, ALL /admin/**".

You can manage the contents of the auth_tokens table using the DynamoDB client from boto3.

How tokens are generated and stored is entirely up to your implementation — a common approach is to create a /login endpoint to issue them.

API Gateway Authorizer

Authorizer is a Lambda function that will validate any request sent to non-public endpoints by verifying its Authorization header, expectedly containing a valid token from the auth_tokens table.

This function will evaluate the each request following the process below:

  • Extract the token from the Authorization header.
  • Retrieve the corresponding record from the auth_tokens DynamoDB table.
  • Verify that the token exists and has not expired (expires_at check).
  • Evaluate route and method permissions using wildcard-compatible patterns (* and **).
  • Return an Allow or Deny policy document to API Gateway accordingly.

The Authorizer function is also available for testing in the local debug server environment (VSCode's F5).