Authorize
In most cases the authorize link is provided in the /connections endpoint. Normally you don't need to manually generate these links.
Use this endpoint to authenticate a user with a connector. It will return a 301 redirect to the downstream connector endpoints.
Auth links will have a state parameter included to verify the validity of the request. This is the url your users will use to activate OAuth supported integration providers.
Vault handles the complete Authorization Code Grant Type Flow for you and will redirect you to the dynamic redirect uri you have appended to the url in case this is missing the default redirect uri you have configured for your Unify application.
CSRF protection with nonce (two-step confirmation)
Optionally pass a nonce query parameter to enable CSRF-protected authorization. When a nonce is supplied and CSRF protection is enabled for your account, the OAuth flow changes from a single step to two steps:
- Vault completes the OAuth exchange but stores the credentials as unconfirmed (confirmed: false). The connection is not callable yet.
- The callback redirect URL is returned with a hash fragment containing the original nonce, a short-lived confirm_token, and the service_id: #nonce=<nonce>&confirm_token=<token>&service_id=<service_id>.
Your application must verify the returned nonce matches the value it sent, then call POST /vault/connections/{unified_api}/{service_id}/confirm with the confirm_token to confirm and activate the connection. Until the connection is confirmed it will not be callable. The confirm_token expires after 30 minutes.
If no nonce is supplied (or CSRF protection is not enabled), the legacy single-step flow is used and the connection becomes callable immediately after the callback — no confirmation step is required.
Path parameters
Service ID of the resource to return
Application ID of the resource to return
Query parameters
An opaque value the applications adds to the initial request that the authorization server includes when redirecting the back to the application. This value must be used by the application to prevent CSRF attacks.
URL to redirect back to after authorization. When left empty the default configured redirect uri will be used.
One or more OAuth scopes to request from the connector. OAuth scopes control the set of resources and operations that are allowed after authorization. Refer to the connector's documentation for the available scopes.
An opaque, single-use value generated by your application to bind the OAuth authorization request to the eventual callback and protect against CSRF. When provided (and CSRF protection is enabled for your account), Vault completes the OAuth flow but leaves the connection in an unconfirmed state: the resulting credentials are stored with confirmed: false and the connection is not callable yet. After the downstream provider redirects back, the callback redirect URL is appended with a hash fragment containing the same nonce, a short-lived confirm_token, and the service_id (e.g. #nonce=<nonce>&confirm_token=<token>&service_id=<service_id>). Your application must verify the returned nonce matches the one it sent and then call the POST /vault/connections/{unified_api}/{service_id}/confirm endpoint with the confirm_token to confirm and activate the connection. The confirm_token is valid for 30 minutes.
Response
Unexpected error
Example response
{
"status_code": 400,
"error": "Bad Request",
"type_name": "RequestHeadersValidationError",
"message": "Invalid Params",
"detail": "Missing Header: x-apideck-consumer-id",
"ref": "https://developers.apideck.com/errors#unauthorizederror"
}