API Keys

API keys (tokens) control access to the MemoryLayer API. Each token carries a name, workspace patterns, scopes, and an optional expiration. Tokens are managed through the /v1/tokens endpoints.

Token Fields

Field	Type	Default	Description
`name`	string	—	Human-readable token name (required)
`principal_type`	string	`User`	Principal type for the token
`workspace_patterns`	string[]	`["*"]`	Workspace access patterns with wildcard support
`scopes`	string[]	`["*"]`	Permission scopes
`expires_in_days`	integer	—	Days until expiration (omit for no expiry)

Create a Token

curl -X POST https://api.memorylayer.ai/v1/tokens \
  -H "Authorization: Bearer $ML_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI Pipeline Token",
    "workspace_patterns": ["ci-*", "staging-*"],
    "scopes": ["*"],
    "expires_in_days": 90
  }'

Response (201 Created):

{
  "id": "42",
  "name": "CI Pipeline Token",
  "principal_type": "User",
  "workspace_patterns": ["ci-*", "staging-*"],
  "scopes": ["*"],
  "created_at": "2026-01-15T10:30:00+00:00",
  "expires_at": "2026-04-15T10:30:00+00:00",
  "revoked": false,
  "token": "ml-abc123...xyz"
}

List Tokens

curl https://api.memorylayer.ai/v1/tokens \
  -H "Authorization: Bearer $ML_API_KEY"

To include revoked tokens in the listing:

curl "https://api.memorylayer.ai/v1/tokens?include_revoked=true" \
  -H "Authorization: Bearer $ML_API_KEY"

Response:

{
  "tokens": [
    {
      "id": "42",
      "name": "CI Pipeline Token",
      "principal_type": "User",
      "workspace_patterns": ["ci-*", "staging-*"],
      "scopes": ["*"],
      "created_at": "2026-01-15T10:30:00+00:00",
      "expires_at": "2026-04-15T10:30:00+00:00",
      "revoked": false
    }
  ]
}

Get Token Details

curl https://api.memorylayer.ai/v1/tokens/42 \
  -H "Authorization: Bearer $ML_API_KEY"

Revoke a Token

Revoking a token invalidates it immediately. The token record is preserved and visible in listings with revoked: true.

curl -X POST https://api.memorylayer.ai/v1/tokens/42/revoke \
  -H "Authorization: Bearer $ML_API_KEY"

Returns 204 No Content on success.

Delete a Token

Permanently removes the token record.

curl -X DELETE https://api.memorylayer.ai/v1/tokens/42 \
  -H "Authorization: Bearer $ML_API_KEY"

Returns 204 No Content on success.

Workspace Pattern Wildcards

Workspace patterns use glob-style matching to control which workspaces a token can access:

Pattern	Matches
`*`	All workspaces
`production`	Only the `production` workspace
`project-*`	`project-alpha`, `project-beta`, etc.
`team-a-*`	`team-a-dev`, `team-a-staging`, `team-a-prod`

A token with ["project-*", "shared"] can access any workspace starting with project- plus the shared workspace.

Token Expiration

Omit expires_in_days (or set to null) to create a token that never expires.
Set expires_in_days to a positive integer to create a time-limited token.
Expired tokens are automatically rejected at authentication time.

Security Best Practices

Scope tokens narrowly. Prefer specific workspace patterns over * for production tokens.
Set expiration dates. Use expires_in_days for CI/CD tokens and short-lived integrations.
Revoke before deleting. Revoke a compromised token immediately, then delete after confirming no active sessions depend on it.
Rotate regularly. Create a new token, update consuming services, then revoke the old one.
Name tokens descriptively. Use names like ci-deploy-staging or monitoring-readonly so the purpose is clear when auditing.
Store securely. Keep tokens in a secrets manager or environment variables, never in source code.