API reference

OAuth 2.0

OAuth 2.0 authorization server endpoints (authorize, token, revoke, introspect, userinfo).

Authorization endpoint

get/oauth/authorize

Starts the Authorization Code flow. Redirect the resource owner here to grant consent. Supports PKCE (`code_challenge` + `code_challenge_method=S256`), strongly recommended for public clients. On approval, the user is redirected back to `redirect_uri` with a short-lived `code` (and the original `state`).

Query parameters

response_typestringrequired
code
client_idstringrequired
redirect_uristring (uri)required
scopestring
statestring
code_challengestring
code_challenge_methodstring
S256

Errors

400Invalid request.

Error envelope and fixes →

curl -X GET "https://api.inaiy.com/oauth/authorize" \
  -H "x-tenant-id: demo" \
  -H "x-api-key: wp_live_xxxxxxxxxxxxxxxxxxxx"

Token endpoint

post/oauth/token

Exchanges an authorization grant for tokens. Supported `grant_type` values: - `authorization_code` (with `code`, `redirect_uri`, and `code_verifier` for PKCE) - `refresh_token` (with `refresh_token`; rotates the refresh token) - `client_credentials` (server-to-server; returns an access token only) Client authentication: HTTP Basic (`client_id`:`client_secret`) or form body `client_id`/`client_secret`.

Request bodyrequired

grant_typestringrequired
One ofauthorization_coderefresh_tokenclient_credentials
codestring
authorization_code grant.
redirect_uristring (uri)
code_verifierstring
PKCE verifier for the authorization_code grant.
refresh_tokenstring
refresh_token grant.
scopestring
client_credentials / down-scoping.
client_idstring
client_secretstring

Response 200Tokens issued.

access_tokenstring
token_typestring
expires_ininteger
scopestring
refresh_tokenstring

Errors

400OAuth error (invalid_request, invalid_grant, unsupported_grant_type, invalid_scope).
401Client authentication failed (invalid_client).

Error envelope and fixes →

curl -X POST "https://api.inaiy.com/oauth/token" \
  -H "x-tenant-id: demo" \
  -H "x-api-key: wp_live_xxxxxxxxxxxxxxxxxxxx"

Request body

{
  "grant_type": "authorization_code",
  "code": "wp_ac_9f8e7d6c...",
  "redirect_uri": "https://app.example.com/callback",
  "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk",
  "refresh_token": "wp_rt_k1l2m3n4...",
  "scope": "contacts.read messages.write",
  "client_id": "wp_client_a1b2c3d4",
  "client_secret": "wp_secret_..."
}

Response 200

{
  "access_token": "wp_at_a1b2c3d4e5f6g7h8i9j0...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "contacts.read messages.write",
  "refresh_token": "wp_rt_k1l2m3n4o5p6q7r8s9t0..."
}

Revocation endpoint (RFC 7009)

post/oauth/revoke

Revokes an access or refresh token. Always returns 200 even if the token was already invalid.

Request bodyrequired

tokenstringrequired
token_type_hintstring
One ofaccess_tokenrefresh_token
client_idstring
client_secretstring

curl -X POST "https://api.inaiy.com/oauth/revoke" \
  -H "x-tenant-id: demo" \
  -H "x-api-key: wp_live_xxxxxxxxxxxxxxxxxxxx"

Request body

{
  "token": "wp_at_a1b2c3d4...",
  "token_type_hint": "access_token",
  "client_id": "wp_client_a1b2c3d4",
  "client_secret": "wp_secret_..."
}

Introspection endpoint (RFC 7662)

post/oauth/introspect

Returns the active state and metadata for an access or refresh token. Requires client authentication.

Request bodyrequired

tokenstringrequired
token_type_hintstring
One ofaccess_tokenrefresh_token
client_idstring
client_secretstring

Response 200Introspection result.

activeboolean
scopestring
client_idstring
token_typestring
expinteger
iatinteger
substring | null
inaiy_token_usestring

curl -X POST "https://api.inaiy.com/oauth/introspect" \
  -H "x-tenant-id: demo" \
  -H "x-api-key: wp_live_xxxxxxxxxxxxxxxxxxxx"

Request body

{
  "token": "wp_at_a1b2c3d4...",
  "token_type_hint": "access_token",
  "client_id": "wp_client_a1b2c3d4",
  "client_secret": "wp_secret_..."
}

Response 200

{
  "active": true,
  "scope": "contacts.read messages.write",
  "client_id": "wp_client_a1b2c3d4",
  "token_type": "Bearer",
  "exp": 1752316205,
  "iat": 1752312605,
  "sub": "6650a1b2c3d4e5f6a7b8c9d0",
  "inaiy_token_use": "access"
}

UserInfo endpoint

get/oauth/userinfo

Returns profile claims for the resource owner associated with the access token. Requires a valid `Authorization: Bearer` access token.

Response 200UserInfo claims.

substring
scopestring
client_idstring

Errors

401Missing or invalid access token.

Error envelope and fixes →

curl -X GET "https://api.inaiy.com/oauth/userinfo" \
  -H "x-tenant-id: demo" \
  -H "x-api-key: wp_live_xxxxxxxxxxxxxxxxxxxx"

Response 200

{
  "sub": "6650a1b2c3d4e5f6a7b8c9d0",
  "scope": "contacts.read messages.write",
  "client_id": "wp_client_a1b2c3d4"
}