Clients API

Clients represent registered applications that interact with HelloJohn. Each client has an ID and secret used during OAuth flows, and can be scoped to specific redirect URIs and grant types.

Client Object

{
  "id": "cli_01HABCDEF111222",
  "tenant_id": "tnt_01HABCDEF654321",
  "name": "My Web App",
  "type": "web",
  "client_id": "cli_01HABCDEF111222",
  "redirect_uris": ["https://app.example.com/auth/callback"],
  "allowed_origins": ["https://app.example.com"],
  "grant_types": ["authorization_code", "refresh_token"],
  "scopes": ["openid", "email", "profile"],
  "post_logout_redirect_uris": ["https://app.example.com/logout"],
  "created_at": "2024-01-10T09:00:00Z"
}

Client Types

Type	Description
`web`	Server-side web application (can keep a secret)
`spa`	Single-page application (public client, uses PKCE)
`native`	Mobile or desktop app (public client, uses PKCE)
`machine`	Server-to-server (client credentials grant)

GET /v1/clients

List all registered clients for the tenant.

curl "https://api.hellojohn.dev/v1/clients" \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "X-Tenant-ID: tnt_01HABCDEF654321"

Response:

{
  "data": [
    {
      "id": "cli_01HABCDEF111222",
      "name": "My Web App",
      "type": "web",
      "redirect_uris": ["https://app.example.com/auth/callback"],
      "created_at": "2024-01-10T09:00:00Z"
    }
  ]
}

POST /v1/clients

Body:

Field	Type	Required	Description
`name`	string	✅	Human-readable name
`type`	string	✅	`web`, `spa`, `native`, `machine`
`redirect_uris`	array	✅	Allowed callback URLs
`allowed_origins`	array	—	CORS origins (for SPA/web)
`grant_types`	array	—	Defaults based on type
`post_logout_redirect_uris`	array	—	Redirect URLs after logout
`scopes`	array	—	Allowed scopes. Default: `openid email profile`

curl -X POST "https://api.hellojohn.dev/v1/clients" \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "X-Tenant-ID: tnt_01HABCDEF654321" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My React App",
    "type": "spa",
    "redirect_uris": [
      "https://app.example.com/auth/callback",
      "http://localhost:3000/auth/callback"
    ],
    "allowed_origins": [
      "https://app.example.com",
      "http://localhost:3000"
    ]
  }'

Response: 201 Created

{
  "id": "cli_01HABCDEF111223",
  "client_id": "cli_01HABCDEF111223",
  "name": "My React App",
  "type": "spa",
  "redirect_uris": [
    "https://app.example.com/auth/callback",
    "http://localhost:3000/auth/callback"
  ]
}

SPA and native clients are public clients and do not have a client secret. They use PKCE for security.

For web and machine type clients, the response includes a client_secret:

{
  "id": "cli_01HABCDEF111224",
  "client_id": "cli_01HABCDEF111224",
  "client_secret": "csec_abc123...",
  "name": "Backend Service",
  "type": "machine"
}

The client_secret is shown only once at creation.

GET /v1/clients/:id

Get details for a specific client.

PATCH /v1/clients/:id

Update a client configuration.

Body (all optional):

Field	Type	Description
`name`	string	New name
`redirect_uris`	array	Replaces existing list
`allowed_origins`	array	Replaces existing list
`post_logout_redirect_uris`	array	Replaces existing list
`scopes`	array	Replaces existing list

DELETE /v1/clients/:id

Delete a client. Active sessions using this client are not affected.

Response: 204 No Content

POST /v1/clients/:id/rotate-secret

Rotate the client secret for a web or machine client.

curl -X POST "https://api.hellojohn.dev/v1/clients/cli_01HABCDEF111224/rotate-secret" \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "X-Tenant-ID: tnt_01HABCDEF654321"

Response: 200 OK

{
  "client_id": "cli_01HABCDEF111224",
  "client_secret": "csec_newvalue...",
  "rotated_at": "2024-01-15T10:00:00Z"
}

GET /v1/clients/:id/tokens

List active tokens issued to this client (machine clients only).

Clients API

On this page