OAuth Clients

Create OAUTH Client

post/v1/oauth-clients

Request

  • Base URL: https://api.withone.ai
  • URL: https://api.withone.ai/v1/oauth-clients
  • Auth: Session (a scheme the document does not define)

Request body

accessTokenTtl604800 | 2592000 | 7776000 | 31536000 | null nullable

Access-token lifetime in seconds. One of the offered choices, or null for the platform default; any other value is refused.

clientTypestring required
consentReasonstring

One sentence an app's owner writes to explain why it asks for access, shown on the consent screen beside the app's name and logo.

Owner-authored, and that is the entire security design. It is set through the client management API, which is session-authenticated and scoped to the client's owner, so writing it requires proving you own the app - the same bar the name and logo already clear, and they are displayed on that screen unfiltered for exactly that reason.

The alternative was carrying it on the authorize URL beside login_hint. That URL is a front-channel GET with no client authentication, so the text would have been written by whoever sent the user the link: caller-supplied prose rendered under a real app's identity, on the one screen where the user decides whether to hand over their accounts. Filtering that safely means recognising every way a destination can be spelled - schemes without slashes, addresses in hex, fullwidth homographs, invisible joiners - and each round of that costs a legitimate sentence somewhere. Moving the write behind authentication removes the attacker rather than the encodings.

So the rules here are about shape, not trust: one line, capped. Nothing screens for destinations, because a URL from the app's own owner is no worse than the homepage URL they already register.

consentSurface'hosted' | 'connect'

Where an OAuth client's users are sent to grant consent.

The surface used to be read off the client id, so a client could only get a different one by being renamed, and every existing client would have moved the moment the rule changed. Naming it on the row makes it a property of the client that its owner can see and set, and leaves the ones already running exactly where they are.

descriptionstring nullable
homepageUrlstring nullable
logoUrlstring nullable
namestring required
redirectUrisstring[] required

Response

OAuth client created; the plain secret is shown once

accessTokenTtlinteger nullable
clientIdstring required
clientSecretstring nullable
clientTypestring required
consentReasonstring nullable

See [OAuthClientView::consent_reason].

consentSurface'hosted' | 'connect' required

Where an OAuth client's users are sent to grant consent.

The surface used to be read off the client id, so a client could only get a different one by being renamed, and every existing client would have moved the moment the rule changed. Naming it on the row makes it a property of the client that its owner can see and set, and leaves the ones already running exactly where they are.

createdAtstring date-time required
descriptionstring nullable
grantTypesstring[] required
homepageUrlstring nullable
idstring required

Prefixed ID with 'oac' prefix (e.g., 'oac_1C'), also accepts raw integer

isActiveboolean required
logoUrlstring nullable
namestring required
redirectUrisstring[] required

Changes

No recorded changes to this operation across all 1 revision of this API.