generated: '2026-07-31' method: searched source: openapi/unqork-customer-api-openapi.yml docs: - https://docs.unqork.io/docs/api-authentication - https://docs.unqork.io/docs/api-access-management - https://docs.unqork.io/docs/api-authentication-bearer-token - https://docs.unqork.io/docs/connect-to-the-unqork-api description: >- The Unqork Customer API authenticates exclusively with OAuth 2.0 bearer tokens. Two grants are supported — client credentials (the default and recommended path) and the resource-owner password grant (off by default, enabled per environment). There are no API keys and no basic-auth path to the resources themselves; HTTP Basic is used only to present client credentials at the token endpoint. Authorization is RBAC, not scopes. summary: types: [oauth2] oauth2_flows: [clientCredentials, password] api_key_in: [] bearer_header: 'Authorization: Bearer {access_token}' token_lifetime_seconds: 3600 scope_based: false authorization_model: rbac applied_globally: true schemes: - name: OAuth2 type: oauth2 applied: >- Document-level `security: [{OAuth2: []}]` — every one of the 93 operations requires a bearer token. flows: - flow: clientCredentials tokenUrl: https://{subdomain}.unqork.io/api/1.0/oauth2/access_token spec_tokenUrl: https://xyzfinancial.unqork.io/api/1.0/oauth2/access_token scopes: 1 scopes_note: single placeholder scope `none` (N/A) — not a real permission rfc: RFC 6749 §1.3.4 recommended: true credential_source: Administration → API Access Management request: >- curl -u '{clientId}:{clientSecret}' -X POST --basic https://{subdomain}.unqork.io/api/1.0/oauth2/access_token -d "grant_type=client_credentials" - flow: password tokenUrl: https://{subdomain}.unqork.io/api/1.0/oauth2/access_token spec_tokenUrl: https://xyzfinancial.unqork.io/api/1.0/oauth2/access_token scopes: 1 rfc: RFC 6749 §1.3.3 recommended: false enabled_by_default: false enablement: >- Administration → Environment Administration → Unqork API → "Enable OAuth2 Password Grant". Once enabled, ALL Unqork users in the environment can exchange their platform username/password for an access token. caveat: >- Removed in OAuth 2.1 and discouraged by RFC 9700 (OAuth 2.0 Security Best Current Practice). Enabling it widens the token-issuing surface to every human account in the environment. request: >- curl -X POST https://{subdomain}.unqork.io/api/1.0/oauth2/access_token -d "grant_type=password&username={username}&password={password}" description: >- The Unqork API implements the OAuth 2.0 Client Credentials Grant and the OAuth 2.0 Password Grant. Client credentials are created on the API Access Management administration page. The token endpoint returns an access_token which expires after one hour, after which a new one must be retrieved. The token is presented on every request as an Authorization: Bearer header. sources: - openapi/unqork-customer-api-openapi.yml credential_surfaces: - name: Express purpose: End-user-facing API access (submissions, workflow execution) in Express View role_requirement: At least one Express Role is required to create a credential role_admin: https://docs.unqork.io/docs/express-role-administration permissions: https://docs.unqork.io/docs/express-permissions revocable: false - name: Creator purpose: Design-time API access (modules, applications, promotions, credentials) role_requirement: At least one Creator Role is required to create a credential role_admin: https://docs.unqork.io/docs/creator-role-administration permissions: https://docs.unqork.io/docs/creator-permissions revocable: true credential_lifecycle: client_id_prefix: uq client_id_example_shape: uq + 24 hex characters secret_visibility: >- The Client Secret is displayed exactly once, in the Client ID & Secret modal at creation time, and is not retrievable afterwards. If lost, an administrator must generate a new secret (the Client ID is retained). expiration_days: {min: 1, max: 730, ui_default: 90} statuses: ACTIVE: Currently active and able to access the API EXPIRES SOON: Set when 15% or less of the validity window remains (14 days on a 90-day credential) EXPIRED: Past the expiration date; can no longer access the APIs REVOKED: Administrator has removed API access (Creator credentials only) LOCKED: >- Temporarily disabled after up to five failed client-secret login attempts; automatically reverts to ACTIVE after 30 minutes managed_via_api: list: credentialsGetAll create: credentialsCreate update: credentialsUpdate revoke: credentialsRevoke delete: credentialsDeleteById delete_is_permanent: true additional_mechanisms: - name: Referstring operation: generateReferString path: POST /referstring description: Generates an encrypted referstring for authentication. note: Mints authentication material — handle like a secret. - name: mTLS with OAuth 2.0 direction: outbound description: >- Client mutual-TLS certificates can be paired with OAuth 2.0 for OUTBOUND integrations from Unqork modules to external services. This is not an inbound securityScheme on the Customer API. docs: https://docs.unqork.io/docs/how-to-setup-an-mtls-certificate-with-oauth-20-authentication - name: SAML SSO scope: platform login, not the Customer API description: >- Unqork supports SAML single sign-on for platform and community access (the Community Hub exposes an ssoType=saml proxy). The Customer API itself is OAuth 2.0 only. - name: PIV/CAC scope: US Government customers description: >- PIV/CAC authentication is offered for US Government deployments as part of Unqork's FedRAMP posture. source: https://unqork.com/security-compliance/ anonymous_access: supported: true context: webhook receivers only note: >- A module configured to receive external webhooks must grant anonymous-user RBAC permissions, which makes its URL publicly callable with no authentication and no signature verification. See asyncapi/unqork-webhooks.yml. discovery: openid_configuration: false oauth_authorization_server_metadata: false note: >- Neither /.well-known/openid-configuration nor /.well-known/oauth-authorization-server (RFC 8414) is served on any Unqork host — see well-known/unqork-well-known.yml. Token endpoint and grant support are documented only in prose and in the OpenAPI securityScheme description. gaps: - No RFC 8414 authorization-server metadata document. - No OIDC / openIdConnect scheme. - No refresh-token flow documented — a one-hour token must be re-minted from credentials. - No scopes, so no way to request a read-only token. - >- No PKCE / authorization-code flow, so there is no delegated-user authorization path for third-party applications. related: scopes: scopes/unqork-scopes.yml conventions: conventions/unqork-conventions.yml lifecycle: lifecycle/unqork-lifecycle.yml