Rotate an app's secret
A new client secret, shown once; the old one stops at once.
/v1/developer/accounts/{n}/oidc-clients/{id}/secret- Access
- Signed request
- Client
- Local or server client
Parameters#
| Name | Location | Meaning |
|---|---|---|
nRequired | Path | The card that owns the apps: a person, or an organisation through an accepted owner. |
idRequired | Path | The app's client_id, `veil_app_` and 32 hex characters. |
This call also needs the common signed-request headers, nonce and timestamp. Prepare and sign request.json before using the example. Request signing
Request examples#
curl -fsS -X POST \
-H "X-Public-Key: $PUBLIC_KEY" -H "X-Signature: $REQUEST_SIGNATURE" \
--json @request.json "https://veil.rip/v1/developer/accounts/1/oidc-clients/veil_app_0123456789abcdef0123456789abcdef/secret"Response#
{client, secret}.
| Field | Type | Meaning |
|---|---|---|
client | OidcClient | The app. |
secret | string | veil_secret_…, once. |
Expand a nested object for its fields. Types ending in null allow a null value; optional fields may be absent. Other fields are present in that object.
App OidcClient
| Field | Type | Meaning |
|---|---|---|
id | string | client_id. |
name | string | The name the consent page shows. |
site | string | null | The app's https site. |
redirectUris | array<string> | Exact redirect URIs. |
postLogoutRedirectUris | array<string> | Where /oidc/logout may send the browser. |
type | string | public or confidential. |
authMethod | string | none, client_secret_basic or private_key_jwt. |
idTokenAlg | string | EdDSA or ES256. |
refresh | boolean | Whether the app gets refresh tokens. |
logo | string | null | The logo's address, with ?v= its hash. |
verified | object | null | {domain}: the owner card proves the domain of the site and of every https redirect URI. |
owner | object | null | {n, name, type, url} of the owner card; null for an app registered without a card. |
dynamic | boolean | Registered through POST /oidc/register. |
createdAt | string | ISO 8601 UTC. |
expiresAt | string | null | A dynamic app's end, 30 days after registration. |
lastUsedAt | string | null | Last sign-in or token. |
jwks | object | null | The public keys of a private_key_jwt app. |
Response headers#
| Header | Value | Meaning |
|---|---|---|
Content-Type | application/json | JSON, also for errors. |
Cache-Control | no-store | Private: never cached. |
Errors#
API errors return an error object. Use error.code for program logic; error.message is English text for people and can change. Response and error guide
| HTTP | Code | Meaning and next step |
|---|---|---|
| 400 | invalid_json | The body is not a JSON object, contains duplicate keys or has trailing data. Send one valid JSON object with |
| 400 | invalid_parameter | A path, query or body field is missing, malformed or outside its accepted range. Correct the field named in |
| 403 | identity_banned | The acting identity is suspended by Veil staff. Wait for the restriction to end or ask staff to review it. |
| 403 | key_mismatch | The signing key does not have authority over this card or operation. Use an active device key with the required owner or member role. |
| 404 | not_found | The requested card, key, alias, code or resource was not found. Check the identifier. Temporary codes and previews may already have expired or been used. |
| 409 | oidc_no_secret | This app authenticates without a client secret (public or private_key_jwt). Nothing to rotate. Change the keys in jwks by registering a new app. |
Shared request errors
| HTTP | Code | Meaning and next step |
|---|---|---|
| 400 | invalid_nonce | The signed-request nonce has an invalid format. Generate a fresh 16 to 128-character nonce using letters, digits, _ or -. |
| 400 | invalid_signature_alg |
Use a supported signing algorithm and matching key/signature encoding. |
| 400 | invalid_timestamp | The signed-request timestamp is not Unix milliseconds. Use an integer Unix timestamp in milliseconds and sign the corrected request. |
| 401 | invalid_signature | The HTTP request signature does not verify. Sign the exact method, path and body bytes, without changing them afterwards. |
| 401 | missing_signature | The request requires a device signature and its headers are missing or unreadable. Send |
| 401 | stale_timestamp | The signed timestamp is outside the accepted clock window. Compare the server Date header with your clock, then generate a fresh nonce, timestamp and signature. |
| 403 | key_banned | The device signing key is suspended by Veil staff. Use an authorised active key or ask staff to review the restriction. |
| 409 | replayed_nonce | The signing key already used this nonce. Check whether the previous request succeeded before making a fresh signed request. |
| 429 | rate_limited | An anonymous, signed-request or API-key allowance was exceeded. Wait at least |
| 500 | internal_error | An unexpected server error occurred. Internal details are not returned. Retry reads with bounded backoff. Check write results before sending a new signed operation. |
| 503 | busy | The application has reached a temporary concurrency or database limit. Wait |