​
Overview

The Obeya Cloud API supports two authentication methods:
  1. Personal Access Tokens (PAT) — For server-to-server and scripting use cases
  2. OAuth 2.0 — For applications that act on behalf of users

​
Personal Access Tokens

​
Creating a Token

Generate tokens from the dashboard at Settings > API Tokens. 
# Use the token in API requests
curl https://acme.obeya.cloud/api/trpc/items.list \
  -H "Authorization: Bearer oby_pat_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"json": {"boardId": "brd_01HXK5..."}}'

​
Token Scopes

ScopeDescription
readRead access to all resources
writeCreate and update resources
deleteDelete resources
adminManage organization settings and members
webhooksManage webhook configurations
Tokens can have one or more scopes. Use the minimum scopes required for your use case.

​
Token Lifecycle

POST /api/auth/tokens
Request: 
{
  "json": {
    "name": "CI/CD Pipeline",
    "scopes": ["read", "write"],
    "expiresIn": "90d"
  }
}
Response: 
{
  "result": {
    "data": {
      "json": {
        "id": "tok_01HXK5...",
        "name": "CI/CD Pipeline",
        "token": "oby_pat_xxxxxxxxxxxxx",
        "scopes": ["read", "write"],
        "expiresAt": "2026-06-17T00:00:00.000Z",
        "createdAt": "2026-03-19T14:30:00.000Z"
      }
    }
  }
}
The token value is only shown once at creation time. Store it securely. If you lose it, generate a new token.

​
Listing Tokens

GET /api/trpc/auth.tokens.list
Returns all tokens for the authenticated user (token values are not included).

​
Revoking a Token

POST /api/trpc/auth.tokens.revoke

{
  "json": {
    "tokenId": "tok_01HXK5..."
  }
}

​
OAuth 2.0

For applications that need to act on behalf of users, use the OAuth 2.0 Authorization Code flow.

​
Register an OAuth Application

  1. Go to Settings > API > OAuth Applications
  2. Click + Register Application
  3. Provide: App name, Redirect URI(s), and requested scopes
  4. Note the Client ID and Client Secret

​
Authorization Flow

1

Redirect to Authorization

Redirect the user to the authorization endpoint:
GET https://obeya.cloud/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &response_type=code
  &scope=read write
  &state=RANDOM_STATE_STRING
2

User Grants Permission

The user reviews and approves the requested permissions.
3

Receive Authorization Code

After approval, the user is redirected to your callback URL:
https://yourapp.com/callback?code=AUTH_CODE&state=RANDOM_STATE_STRING
4

Exchange Code for Token

Exchange the authorization code for an access token:
POST https://obeya.cloud/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE
&redirect_uri=https://yourapp.com/callback
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
Response:
{
  "access_token": "oby_oat_xxxxxxxxxxxxx",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "oby_ort_xxxxxxxxxxxxx",
  "scope": "read write"
}
5

Use the Access Token

Include the access token in API requests:
curl https://acme.obeya.cloud/api/trpc/items.list \
  -H "Authorization: Bearer oby_oat_xxxxxxxxxxxxx"

​
Refreshing Tokens

Access tokens expire after 1 hour. Use the refresh token to get a new access token: 
POST https://obeya.cloud/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=oby_ort_xxxxxxxxxxxxx
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

​
Verifying the Current User

GET /api/trpc/auth.me
Returns the authenticated user’s profile and organization memberships: 
{
  "result": {
    "data": {
      "json": {
        "id": "usr_01HXK5...",
        "email": "alice@company.com",
        "name": "Alice Johnson",
        "avatar": "https://...",
        "memberships": [
          {
            "organizationId": "org_01HXK5...",
            "organizationSlug": "acme",
            "role": "admin"
          }
        ]
      }
    }
  }
}