Payrails Authentication

generated: '2026-07-20'
method: searched
source: https://docs.payrails.com/reference/getoauthtoken
docs: https://docs.payrails.com/docs/api-credentials-1
summary:
  types: [oauth2, mutualTLS]
  oauth2_flows: [clientCredentials]
  notes: >-
    Backend services exchange a Client ID + Client Secret (scoped per environment)
    for a short-lived bearer access token, then call Payrails APIs with that token.
    Access tokens are valid for one hour and must be refreshed on expiry. mTLS is
    additionally available to secure the connection to Payrails. Credentials are
    created and scoped per environment (Staging vs Production) in the Payrails Portal.
schemes:
  - name: OAuth2ClientCredentials
    type: oauth2
    flow: clientCredentials
    token_url: https://api.payrails.io/auth/token/{clientId}
    token_url_staging: https://api.staging.payrails.io/auth/token/{clientId}
    token_lifetime_seconds: 3600
    request: POST with Client ID (path) + Client Secret credential
    response_field: access token with expires_in
    applied_as: Authorization bearer token on all API calls
    source: https://docs.payrails.com/reference/getoauthtoken
  - name: mTLS
    type: mutualTLS
    docs: https://docs.payrails.com/docs/mtls-configuration-1
    notes: Mutual TLS client-certificate connection option for backend integrations.
  - name: WebhookHMAC
    type: hmac
    scope: inbound-notifications
    algorithm: HMAC-SHA256
    header: X-Signature
    encoding: base64
    docs: https://docs.payrails.com/docs/receive-notifications
    notes: >-
      Notifications carry an X-Signature header (base64 HMAC-SHA256 of the payload
      using a portal-generated secret) so receivers can verify authenticity. This
      secures inbound webhooks, not outbound API auth.
roles_permissions:
  model: RBAC (roles & permissions assigned per API service / workspace)
  docs: https://docs.payrails.com/docs/roles-permissions
sso:
  saml: true
  docs: https://docs.payrails.com/docs/single-sign-on