Authenticate and authorize API requests

Most external Usable REST integrations authenticate with a personal access token (PAT):

Authorization: Bearer <personal-access-token>

A PAT represents a user and its configured scope. It does not grant more access than the user has, and it can be narrower than the user's dashboard access.

Create a least-privilege token

Create PATs from the account interface or the released token-management API. For each integration:

1. Give the token a descriptive name.
2. Select only required workspaces.
3. Grant only required actions.
4. Set an appropriate expiry where supported.
5. Copy the secret once into an approved secret manager.
6. Test the smallest expected read before allowing writes.

Use separate tokens for separate services and environments. Do not share one broad personal token across applications.

See Personal access tokens for lifecycle guidance.

Send the token

curl "https://usable.dev/api/memory-fragments?workspaceId=<workspace-id>&limit=20" \
  -H "Authorization: Bearer <personal-access-token>" \
  -H "Accept: application/json"

Send tokens only over HTTPS. Do not put them in query strings, URLs, fragment content, browser storage accessible to unrelated scripts, or telemetry.

Validate access

Where supported, validate a bearer token with:

curl https://usable.dev/api/auth/validate-token \
  -H "Authorization: Bearer <personal-access-token>"

Validation confirms the credential's current acceptance and reported access. The target endpoint still performs its own resource and workspace checks.

A successful workspace read does not prove write access. Test the exact operation in a safe workspace.

Permissions are workspace-scoped

Effective authorization combines:

• token validity and expiry;
• token permission set;
• the issuing user's current account access;
• workspace membership or public subscription;
• the requested resource and action;
• route-specific role requirements.

A token can work in one workspace and fail in another. Public subscription is read-style access and does not grant mutation rights.

Use Workspace roles and permissions to understand the human role boundary.

Browser-session routes

Some dashboard and administration routes require a signed-in browser session even when nearby resource routes accept bearer tokens. The deployed OpenAPI security definition and route documentation determine supported auth.

Do not automate a browser-session-only route by copying cookies or CSRF values into a service. Use a documented bearer-token route, MCP tool, or supported dashboard workflow.

Understand 401, 403, and 404

401 Unauthorized

Authentication is missing, invalid, expired, or unavailable.

• Confirm the Bearer scheme and header formatting.
• Check expiry and revocation.
• Rotate a compromised or uncertain token.
• Do not repeatedly retry an invalid credential.

403 Forbidden

The caller is authenticated but lacks the required permission, workspace role, tier, or route-specific authority.

• Confirm the workspace ID.
• Inspect the token's scope.
• Check the user's current workspace role.
• Grant only the missing capability.

404 Not Found

The object may not exist, may have been archived or deleted, or may be hidden from this caller to preserve the access boundary.

Do not use response differences to enumerate private resources. Verify the ID and workspace using an identity that should already have access.

Rotate and revoke

Rotate a token when:

• it may have been exposed;
• an operator or service changes;
• its permissions are too broad;
• its lifetime no longer matches the integration;
• the application is moved between environments.

Update the secret consumer, verify the replacement, then revoke the old token. Revoke immediately after confirmed exposure.

Released token-management routes include list, create, inspect, update, revoke, and analytics operations under /api/tokens. Consult /api/docs for exact schemas and route authentication.

Service and browser security

• Keep PAT use on trusted servers where possible.
• Never expose a broad PAT in browser JavaScript.
• Redact Authorization, cookies, token values, and signed URLs from logs.
• Restrict outbound destinations to prevent credential forwarding.
• Do not send credentials to an AI model.
• Review token use and remove inactive integrations.

Troubleshooting checklist

1. Fetch /api/docs from the target environment.
2. Confirm the endpoint accepts bearer authentication.
3. Confirm token expiry and revocation state.
4. Confirm workspace membership and token scope.
5. Verify the resource belongs to that workspace.
6. Distinguish authentication failure from authorization failure.
7. Record status, route, method, time, and non-sensitive request context.

Related pages

• REST API overview
• Requests, responses, pagination, and errors
• Personal access tokens
• Workspace roles and permissions