Create an auth profile

POST 
/v1/auth-profiles

Register an OAuth2 client credentials profile that the platform uses to authenticate to your webhook endpoint. Requires the connector:auth-profiles:create scope and an Idempotency-Key header. Creating a profile has no effect on deliveries until you bind it to a webhook with POST /v1/webhooks/{webhook_id}/bind.

How the platform uses the profile

Before delivering to a webhook bound to this profile, the platform requests a token from token_endpoint_url:

POST /oauth2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=lyriq-webhook-sender&client_secret=...&scope=webhooks.receive

The client credentials are sent in the form body (client_secret_post). Your token endpoint must answer 2xx with a JSON body containing access_token and, optionally, expires_in in seconds (300 is assumed when absent). The platform caches the token per profile and requests a new one 30 seconds before it expires, or immediately after the profile is updated. The token is sent on each delivery as Authorization: Bearer <access_token>; the HMAC signature is sent as well.

If the token endpoint times out, cannot be reached, or answers 429 or 5xx, the delivery is retried later. Any other error status, or a body without access_token, fails the delivery permanently. The token endpoint must be an https:// URL that resolves to a public address.

Request and result

All attributes are required. client_id, client_secret and requested_scope must not be empty; token_endpoint_url must be an absolute https:// URL with a host. profile_type must be OAuth2. The response is 202 Accepted; the new auth_profile_id is the relationships.resource.data.id of GET /v1/operations/{operation_id}. Retrying with the same Idempotency-Key and body returns the same 202 document without creating a second profile.

Request

Responses

202

Accepted. The operation (data.id) tracks the creation; read the new auth_profile_id from the operation's relationships.resource.

400

A field is empty or invalid (for example token_endpoint_url is not an https:// URL), or the Idempotency-Key header is missing.

401

The bearer token is missing, malformed, expired, signed by an unknown key, or was not issued by the platform IAM for the Lyriq Connector. Obtain a new token and retry. See the Authentication section.

403

The token is valid but may not perform this request: it lacks the required scope, has no bank membership, needs an x-dan-bank-id header to choose between several memberships, names a bank in x-dan-bank-id it has no membership for, or the caller's bank is suspended or terminated. A new token with the same configuration fails the same way. See the Authentication section.

409

The request conflicts with an earlier request or with the current state of the target: an Idempotency-Key reused with a different body (IDEMPOTENCY_CONFLICT), a request with the same key still in progress (IDEMPOTENCY_PENDING), or a target resource in a state that does not allow the request (STATE_CONFLICT).

422

The request is well-formed JSON but cannot be processed: the body does not match the expected shape (a missing or unknown member, a wrong type, or a wrong data.type), or it breaks a business or cross-field rule. Correct the request before retrying.

429

The request was refused because a rate limit was reached (code RATE_LIMITED). No Retry-After header is sent; retry with exponential backoff.

503

The request could not be served right now. Either the network is not fully operational (OUTBOUND_HALTED or READ_ONLY: mutations are refused while read endpoints keep working; OPERATIONAL_STATE_UNKNOWN: the state could not be determined), or a platform dependency is temporarily unavailable. No Retry-After header is sent; retry later with backoff. When retrying a mutation, reuse the same Idempotency-Key and body.