Client Registration (RFC 7591)

Dynamic Client Registration (RFC 7591) lets your application register as an OAuth client without manual intervention from the Whatalo team. Each installation of the same software can obtain its own client_id.

Endpoint

POST https://app.whatalo.com/oauth/register
Content-Type: application/json

No prior authentication required. The endpoint is public.

This endpoint has a limit of 10 requests per IP per hour. If exceeded, you will receive HTTP 429 with a Retry-After header. Cache the received client_id — you do not need to register again on every session.

Request body

{
  "client_name": "My SaaS Integration",
  "redirect_uris": ["https://my-app.com/oauth/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "scope": "read:orders read:products write:orders",
  "token_endpoint_auth_method": "client_secret_post",
  "software_id": "my-saas-integration",
  "software_version": "2.1.0",
  "logo_uri": "https://my-app.com/logo.png",
  "client_uri": "https://my-app.com",
  "policy_uri": "https://my-app.com/privacy",
  "tos_uri": "https://my-app.com/terms"
}

Request body fields

Field	Required	Description
`client_name`	Yes	Name shown on the consent screen
`redirect_uris`	Yes	List of redirect URIs. Must be HTTPS (except `localhost`)
`grant_types`	No	Defaults to `["authorization_code"]`. Include `"refresh_token"` if you need refresh
`response_types`	No	Only `["code"]` is supported
`scope`	No	Scopes the app may request. See Scopes
`token_endpoint_auth_method`	No	`"client_secret_post"`, `"client_secret_basic"`, or `"none"` (public client)
`software_id`	No	Stable software identifier, shared across all instances
`software_version`	No	Opaque software version, for audit purposes only
`logo_uri`	No	App logo URL (shown on the consent screen)
`client_uri`	No	App homepage URL
`policy_uri`	No	Privacy policy URL
`tos_uri`	No	Terms of service URL

Successful response (201 Created)

{
  "client_id": "abc123def456ghi789jkl012",
  "client_secret": "s3cr3t_v4lu3_xyz987wvu654",
  "client_name": "My SaaS Integration",
  "redirect_uris": ["https://my-app.com/oauth/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "scope": "read:orders read:products write:orders",
  "token_endpoint_auth_method": "client_secret_post",
  "software_id": "my-saas-integration",
  "software_version": "2.1.0",
  "client_id_issued_at": 1746648000,
  "client_secret_expires_at": 0
}

Response fields (RFC 7591 §3.2.1)

Field	Type	Description
`client_id`	string	Unique client identifier. Store persistently.
`client_secret`	string	Client secret (confidential clients only). Shown only once.
`client_id_issued_at`	number	UNIX timestamp (seconds) when the `client_id` was issued.
`client_secret_expires_at`	number	UNIX expiry timestamp (seconds). For dynamically registered (DCR) clients, this is set to 90 days from `client_id_issued_at` by default. Manually-created clients from the developer portal return `0` (no expiration).

The client_secret is shown only in this response. Store it immediately in a secure secrets manager — you will not be able to retrieve it again.

DCR client lifetime: Dynamically registered clients are automatically purged after they expire. If your app receives invalid_client (HTTP 401) on /oauth/token, simply re-register at POST /oauth/register to obtain new credentials. Standard OAuth clients handle this transparently.

Public clients (no secret)

If your app cannot securely maintain a secret (desktop application, browser extension, CLI tool), register it as a public client:

{
  "client_name": "My Desktop App",
  "redirect_uris": ["http://127.0.0.1:PORT/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "token_endpoint_auth_method": "none"
}

The response will not include client_secret. The PKCE authorization flow remains mandatory.

The `software_id` pattern

Each installation of the same software gets a distinct client_id — that is by design (RFC 7591 §2). The software_id field lets Whatalo identify the software package independently of the instance.

Field	Per instance	Stable across instances
`client_id`	Yes	No
`software_id`	No	Yes — choose a fixed value for your software

When the Whatalo team verifies a software_id, all instances automatically inherit the verified badge on the consent screen.

Next step

With your client_id in hand, start the authorization flow.

On this page