Skip to content

Bearer Tokens & Access Control

As mentioned in the API Configuration topic, when enable_auth is set as true, Atlas automatically creates the auth_tokens DynamoDB table and, if any private endpoint is present, it also enables the API Gateway Authorizer.

This topic explains how to properly interact with the auth_tokens table and describes the security behavior of both the API Gateway Authorizer and the WebSocket.

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. It serves as a bearer token used for authorizing requests to non-public endpoints via the Authorization header. It is also used as the authentication token for connecting to the API's WebSocket (if private) and for sending messages to private WebSocket actions.

  • expires_at: The token's time to live (in seconds). DynamoDB automatically deletes the token when it expires (not immediately, just best-effort).

  • 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 REST endpoints and WebSocket actions accessible by this token. It must follow any of the formats: HTTPMETHOD_OR_ALL endpoint_route or WS channel_name.action_name, separated by a comma and a space. Example: "GET /users/*, POST /orders, ALL /admin/**, WS echo.ping, WS samplechannel.*, WS *.*".

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).

WebSocket "Authorizer"?

The WebSocket equivalent of the API Gateway Authorizer is the @action_method decorator itself.