Skip to main content
The Yertle API uses JWT bearer tokens issued by AWS Cognito. Every request to a protected endpoint must include an Authorization header.

​
Header format

​
Getting a token

The easiest way is to log in with the Yertle CLI:
The CLI writes the token to ~/.yertle/config.json:
The CLI also handles automatic token refresh — if you use the CLI itself for API calls, you don’t need to think about expiration.

​
Option 2: Direct Cognito authentication

If you can’t use the CLI, you can authenticate directly with Cognito using the AWS SDK or any Cognito-compatible client. The user pool details are exposed by Yertle’s frontend at build time and can be found in the public auth flow. The Yertle CLI source (model-context/yertle-cli) is a reference implementation you can study.

​
Token lifetime

  • Access tokens expire after one hour
  • Refresh tokens are valid for 30 days
  • The CLI automatically refreshes access tokens using the stored refresh token; SDKs and custom clients should do the same

​
Errors

When you receive a 401, refresh your token (or re-run yertle auth login) and retry.

​
Permissions and roles

Authentication identifies who you are. Authorization is enforced per organization based on your role: See Concepts for more on roles and the organization model.