Skip to content

Authentication API

Endpoints for user authentication and API key management.

Login

POST /auth/login

Exchange Clerk session for AMP token.

Request

curl -X POST https://api.amp.dev/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "clerk_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-01-15T11:30:00Z",
  "user": {
    "id": "usr_2xK9mPqR4vN8sT3w",
    "email": "user@example.com",
    "name": "John Doe"
  },
  "tenant": {
    "id": "tnt_xxx",
    "name": "Acme Corp"
  }
}

Refresh Token

POST /auth/refresh

Refresh an expiring JWT token.

Request

curl -X POST https://api.amp.dev/v1/auth/refresh \
  -H "Authorization: Bearer $CURRENT_TOKEN"

Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-01-15T12:30:00Z"
}

Logout

POST /auth/logout

End the current session.

Request

curl -X POST https://api.amp.dev/v1/auth/logout \
  -H "Authorization: Bearer $AMP_TOKEN"

Response

{
  "success": true
}

Who Am I

GET /auth/whoami

Get current user and tenant information.

Request

curl https://api.amp.dev/v1/auth/whoami \
  -H "Authorization: Bearer $AMP_API_KEY"

Response

{
  "user": {
    "id": "usr_2xK9mPqR4vN8sT3w",
    "email": "user@example.com",
    "name": "John Doe",
    "role": "admin"
  },
  "tenant": {
    "id": "tnt_xxx",
    "name": "Acme Corp",
    "slug": "acme-corp"
  },
  "auth_method": "api_key",
  "scopes": ["missions:read", "missions:write", "content:read"]
}

Create API Key

POST /auth/keys

Create a new API key.

Request

curl -X POST https://api.amp.dev/v1/auth/keys \
  -H "Authorization: Bearer $AMP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Server",
    "scopes": ["missions:read", "missions:write", "content:read"],
    "expires_in_days": 365
  }'

Parameters

Parameter Type Required Description
name string Yes Descriptive name for the key
scopes array No Permissions (defaults to all)
expires_in_days integer No Expiration in days (null = never)

Available Scopes

Scope Description
missions:read Read mission data
missions:write Create/update missions
content:read Read content
content:write Approve/reject content
analytics:read Read analytics
integrations:read View integrations
integrations:write Manage integrations
admin Full access

Response

{
  "id": "key_3yL0mPqR5wN9tU4v",
  "name": "Production Server",
  "key": "amp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "key_prefix": "amp_live_xxxx",
  "scopes": ["missions:read", "missions:write", "content:read"],
  "expires_at": "2025-01-15T10:30:00Z",
  "created_at": "2024-01-15T10:30:00Z"
}

Store Your Key

The full API key is only shown once. Store it securely before leaving this page.

List API Keys

GET /auth/keys

List all API keys for the current tenant.

Request

curl https://api.amp.dev/v1/auth/keys \
  -H "Authorization: Bearer $AMP_API_KEY"

Response

{
  "data": [
    {
      "id": "key_3yL0mPqR5wN9tU4v",
      "name": "Production Server",
      "key_prefix": "amp_live_xxxx",
      "scopes": ["missions:read", "missions:write"],
      "last_used_at": "2024-01-15T09:45:00Z",
      "expires_at": "2025-01-15T10:30:00Z",
      "status": "active",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "key_4zM1nQrS6xO0uV5w",
      "name": "Analytics Dashboard",
      "key_prefix": "amp_live_yyyy",
      "scopes": ["analytics:read"],
      "last_used_at": null,
      "expires_at": null,
      "status": "active",
      "created_at": "2024-01-10T08:00:00Z"
    }
  ],
  "has_more": false,
  "total": 2
}

Get API Key

GET /auth/keys/:id

Get details for a specific API key.

Request

curl https://api.amp.dev/v1/auth/keys/key_3yL0mPqR5wN9tU4v \
  -H "Authorization: Bearer $AMP_API_KEY"

Response

{
  "id": "key_3yL0mPqR5wN9tU4v",
  "name": "Production Server",
  "key_prefix": "amp_live_xxxx",
  "scopes": ["missions:read", "missions:write"],
  "last_used_at": "2024-01-15T09:45:00Z",
  "expires_at": "2025-01-15T10:30:00Z",
  "status": "active",
  "usage": {
    "total_requests": 12456,
    "last_30_days": 3421
  },
  "created_at": "2024-01-15T10:30:00Z"
}

Revoke API Key

DELETE /auth/keys/:id

Revoke an API key immediately.

Request

curl -X DELETE https://api.amp.dev/v1/auth/keys/key_3yL0mPqR5wN9tU4v \
  -H "Authorization: Bearer $AMP_API_KEY"

Response

{
  "id": "key_3yL0mPqR5wN9tU4v",
  "status": "revoked",
  "revoked_at": "2024-01-15T10:35:00Z"
}

Rotate API Key

POST /auth/keys/:id/rotate

Create a new key and schedule the old one for revocation.

Request

curl -X POST https://api.amp.dev/v1/auth/keys/key_3yL0mPqR5wN9tU4v/rotate \
  -H "Authorization: Bearer $AMP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "grace_period_days": 7
  }'

Parameters

Parameter Type Default Description
grace_period_days integer 7 Days until old key is revoked

Response

{
  "old_key": {
    "id": "key_3yL0mPqR5wN9tU4v",
    "status": "rotating",
    "valid_until": "2024-01-22T10:35:00Z"
  },
  "new_key": {
    "id": "key_5aO2pSsU7zB0vX6y",
    "key": "amp_live_new_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "key_prefix": "amp_live_new_",
    "scopes": ["missions:read", "missions:write"],
    "created_at": "2024-01-15T10:35:00Z"
  }
}

Zero-Downtime Rotation

Both keys work during the grace period. Update your systems to use the new key before the grace period ends.

Errors

401 Unauthorized

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or expired API key"
  }
}

403 Forbidden

{
  "error": {
    "code": "forbidden",
    "message": "API key does not have required scope: missions:write"
  }
}

404 Not Found

{
  "error": {
    "code": "not_found",
    "message": "API key not found"
  }
}