Skip to main content
POST
Create a provider config with authenticated onboarding

Authorizations

Authorization
string
header
required

You can use an OAuth2 JWT bearer token in the Authorization header of your API requests for supported endpoints: Authorization: Bearer <YOUR_JWT_HERE>. These tokens are valid for 10 minutes and can be requested via the access token endpoint endpoint.

Headers

x-idempotency-key
string<uuid>
required

Idempotency key to be used. Sending again the same key would return the same result without re-executing the update.

Path Parameters

providerId
string<uuid>
required

Identifier of the resource in Payrails.

Body

application/json

Parameters for authenticated provider onboarding. authentication carries the credentials returned by the onboarding flow, depending on the authentication mode.

accountName
string<string>
required

Account name of the provider.

Pattern: ^[a-zA-Z0-9_-]*$
authenticationMode
enum<string>
required

Authentication mode used for provider onboarding.

Available options:
none,
oauth,
trackingId
id
string<uuid>

Optional ID for the provider configuration. If not specified, a new ID is automatically generated.

config
object
accountDisplayName
string<string>

Account display name of the provider.

workspaces
string<uuid>[]

List of workspaces that the provider configuration will be assigned.

workspaceId
string<uuid> | null
deprecated

Deprecated (use workspaces), Workspace ID that the provider configuration will be assigned.

additionalData
object

Custom key-value data included in authorization webhook notifications. Do not store secrets, credentials, or personally identifiable information (PII).

authentication
object

Provider onboarding credentials returned by the authentication flow.

Response

Created.

id
string<uuid>
required

Unique identifier of the provider config.

providerId
string<uuid>
required

Unique identifier of the provider.

accountName
string<string>
required

Account name of the provider.

Pattern: ^[a-zA-Z0-9_-]*$
configSchema
string
required

JSON schema of the provider configuration.

createdAt
string<date-time>
required

Date of creation of the provider config.

accountDisplayName
string<string>
required

Account display name of the provider.

status
string

The status of the provider config.

config
object
workspaces
string<uuid>[]

Workspaces that the Provider config belongs to.

providerName
string

Name of the provider.

providerDisplayName
string

Display name of the provider.

notificationUrl
string

Notification URL for this provider config.

additionalData
object

Custom key-value data included in authorization webhook notifications. Do not store secrets, credentials, or personally identifiable information (PII).

Last modified on October 1, 2026