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 multiple active tokens.

Token Management

List Your Tokens

List all personal access tokens for the authenticated user.

GET /api/tokens/
Authorization: Bearer your-access-token

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

Response

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

Create a Token

Create a new personal access token.

POST /api/tokens/
Authorization: Bearer your-access-token
 
{
    "name": "API Access Token",
    "expires_at": "2024-12-31T23:59:59Z"
}

Response

{
    "id": "uuid",
    "name": "API Access Token",
    "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

Revoke an existing personal access token.

DELETE /api/tokens/{token_id}/
Authorization: Bearer your-access-token

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

Using Tokens for Authentication

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

GET /api/brains/
Authorization: Bearer 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. Token Management: Users can have multiple active tokens for different purposes.
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: Invalid token creation request