Authentication

The Driftwood API supports two authentication methods: user tokens (for interactive sessions) and OAuth app credentials (for integrations and automated access).

Bearer Token Authentication

All authenticated requests must include an Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

Method 1: User Authentication

Use email/password login to get access and refresh tokens. Best for user-facing applications.

Register

curl -X POST https://api.driftwoodapp.com/api/auth-register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your-secure-password",
    "name": "Your Name"
  }'

Response:

{
  "ok": true,
  "result": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "dGhpcyBpcyBhIHJlZnJl...",
    "expires_in": 900,
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "you@example.com",
      "name": "Your Name",
      "role": "owner"
    }
  }
}

Login

curl -X POST https://api.driftwoodapp.com/api/auth-login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your-password"
  }'

Response: Same format as register.

Refresh Token

Access tokens are short-lived. Use the refresh token to get a new pair:

curl -X POST https://api.driftwoodapp.com/api/auth-refresh-token \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "dGhpcyBpcyBhIHJlZnJl..."}'

Response:

{
  "ok": true,
  "result": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "bmV3IHJlZnJlc2ggdG9r...",
    "expires_in": 900
  }
}

Caution

Refresh tokens are single-use. Each refresh returns a new refresh token — always store and use the latest one.

Logout

curl -X POST https://api.driftwoodapp.com/api/auth-logout \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Method 2: OAuth App Authentication

Use OAuth apps for server-to-server integrations. OAuth apps use the client credentials grant type to obtain access tokens.

Step 1: Create an OAuth App

Create an app from the Driftwood UI or via the API:

curl -X POST https://api.driftwoodapp.com/api/oauth-apps-create \
  -H "Authorization: Bearer YOUR_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Integration"}'

Response:

{
  "ok": true,
  "result": {
    "app": {
      "id": "app-uuid-here",
      "name": "My Integration",
      "client_id": "dw_ci_abc123def456",
      "client_secret_prefix": "dw_cs_"
    },
    "client_secret": "dw_cs_full_secret_value_here"
  }
}

Caution

The client_secret is only returned once at creation time. Store it securely — you cannot retrieve it again.

Step 2: Exchange Credentials for a Token

curl -X POST https://api.driftwoodapp.com/api/oauth-token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "dw_ci_abc123def456",
    "client_secret": "dw_cs_full_secret_value_here"
  }'

Response:

{
  "ok": true,
  "result": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "bearer",
    "expires_in": 3600
  }
}

Step 3: Use the Token

curl -X POST https://api.driftwoodapp.com/api/contacts-list \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"limit": 10}'

OAuth app tokens have the same access as the user who created the app, scoped to their account.

Managing OAuth Apps

Operation	Endpoint	Description
Create	oauth-apps-create	Create a new OAuth app
List	oauth-apps-list	List all OAuth apps
Revoke	oauth-apps-revoke	Permanently revoke an app

List apps:

curl -X POST https://api.driftwoodapp.com/api/oauth-apps-list \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"include_revoked": false}'

Token Lifetimes

Token Type	Lifetime
User access token	15 minutes
User refresh token	30 days
OAuth access token	1 hour

JWT Claims

Access tokens are JWTs containing:

Claim	Description
user_id	The authenticated user’s UUID
account_id	The account UUID (user tokens only)
token_type	"user", "admin", or "oauth_client"
exp	Token expiration timestamp