Personal Access Tokens

Personal Access Tokens (PATs) are used for authenticating with the BrainMaps API, especially when using the CLI or making programmatic API calls. Each user can have one active token at a time.

Token Management

List Your Tokens

GET /api/tokens/
Authorization: Bearer <jwt_token>

Returns a list of your active (non-revoked) tokens.

Response

{
    "results": [
        {
            "id": "uuid",
            "created_at": "2023-12-22T12:00:00Z",
            "expires_at": "2024-12-22T12:00:00Z",
            "is_revoked": false
        }
    ]
}

Create a Token

POST /api/tokens/
Authorization: Bearer <jwt_token>

Creates a new personal access token. If you already have an active token, you must revoke it first.

Response

{
    "id": "uuid",
    "created_at": "2023-12-22T12:00:00Z",
    "expires_at": "2024-12-22T12:00:00Z",
    "is_revoked": false,
    "token": "your-token-value"  // Only shown once upon creation
}

Important: The token value is only returned once when the token is created. Make sure to save it securely as you won’t be able to retrieve it again.

Revoke a Token

POST /api/tokens/{token_id}/revoke/
Authorization: Bearer <jwt_token>

Revokes an existing token, making it invalid for future authentication.

Response

{
    "status": "token revoked"
}

Using Tokens for Authentication

Once you have a token, you can use it to authenticate API requests:

GET /api/brains/
Authorization: Token <your-token-value>

Token Authentication in the CLI

When using the BrainMaps CLI, you can authenticate using your token:

# Set your token in the CLI configuration
brainmaps config set-token <your-token-value>
 
# The CLI will now use this token for all requests
brainmaps list-brains

Security Considerations

1. Token Storage: Store tokens securely and never commit them to version control.
2. One Token Per User: Users can only have one active token at a time.
3. Token Revocation: Tokens can be revoked at any time if compromised.
4. Token Expiration: Tokens may have an expiration date after which they become invalid.
5. Token Visibility: Users can only see and manage their own tokens.

Error Responses

• 401 Unauthorized: Invalid or expired token
• 403 Forbidden: Attempting to access another user’s tokens
• 400 Bad Request: Attempting to create a token when one already exists