Skip to main content
All Uplint API requests require authentication via the Authorization header. Uplint supports two authentication methods: API keys (for programmatic access) and JWT tokens (for dashboard sessions).

​
API keys

API keys are the primary way to authenticate with the Uplint API. Each key is scoped to a specific set of permissions and is bound to a tenant.

​
Format

API keys follow the format ul_live_ followed by a random string: 
ul_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

​
Usage

Pass the key in the Authorization header: 
# With Bearer prefix (recommended)
curl -H "Authorization: Bearer ul_live_a1b2c3d4..." https://api.uplint.dev/api/v1/files

# Without prefix (also accepted)
curl -H "Authorization: ul_live_a1b2c3d4..." https://api.uplint.dev/api/v1/files

​
Scopes

Each API key carries one or more permission scopes:
ScopeDescription
uploadUpload files to any context
downloadGenerate download URLs for files
metadataRead file metadata and list files
deleteDelete files
adminFull access — includes all scopes plus API key and context management
When creating a key, assign only the scopes it needs. A backend service that uploads and reads files only needs upload, download, and metadata.

​
Key lifecycle

API keys have three states:
  • Active — The key works normally.
  • Disabled — The key is temporarily deactivated. It can be re-enabled at any time.
  • Revoked — The key is permanently deactivated. This action is irreversible.

​
Expiration

Keys can be created with an expiration date (1–365 days) or without one. Expired keys are automatically treated as revoked.

​
Security best practices

  • Store keys securely. The full key is only returned once at creation time. Use a secrets manager or environment variables — never commit keys to source code.
  • Use least-privilege scopes. Only grant the permissions each key needs.
  • Rotate keys regularly. Create new keys and revoke old ones on a schedule.
  • Set expiration dates. For time-limited integrations, set expires_in_days at creation.
  • Monitor usage. Check last_used_at in key details to detect unused or compromised keys.

​
JWT tokens

JWT tokens are used by the Uplint dashboard and are issued during login. They carry the user’s identity and tenant context. For programmatic access, use API keys instead of JWT tokens.

​
Error responses

Authentication failures return a 401 status: 
{
  "status": "ERROR",
  "message": "Invalid or missing API key",
  "errors": ["Authentication required"],
  "timestamp": "2026-02-10T12:00:00Z"
}
Common causes:
  • Missing Authorization header
  • Expired API key
  • Disabled or revoked API key
  • Key doesn’t have the required scope for the endpoint