Vault
Authorizations
Authorize third-party services and manage one-time links and return URLs.
Authorize third-party services and manage one-time links and return URLs.
Authorization produces a secret of kind oauth for services that support OAuth. Create an authorization and give connect_url to the end user; once they approve on the confirmation page and on the service, the secret is written to the vault and the platform keeps it refreshed. The confirmation page, the callback and the client metadata need no API Key.
Create authorization
POST /vault/v1/authorizations
Request body
| Field | Type / enum | Required | Description |
|---|---|---|---|
| vault_id | string | yes | Vault ID |
| template_id | "linear" / "atlassian" | no | OAuth template ID; provide exactly one of template_id or resource_url |
| resource_url | string | no | Resource URL to authorize |
| return_url | string | no | Return URL; must be on the account allowlist |
Response
HTTP 200
application/json
| Field | Type / enum | Required | Description |
|---|---|---|---|
| id | string | yes | Object ID |
| type | "vault_authorization" | yes | Object type |
| vault_id | string | yes | Vault ID |
| status | "pending" / "authorizing" / "completed" / "failed" / "expired" | yes | Current status |
| resource | string | yes | Authorized resource URL |
| secret_name | string | yes | Associated secret name |
| connect_url | string | yes | One-time confirmation page, valid for 30 minutes |
| client_registration | "cimd" / "dcr" / null | yes | cimd: Client ID Metadata Document; dcr: Dynamic Client Registration; null before registration |
| secret_id | string / null | yes | Associated secret ID, or null |
| error | object / null | yes | Failure details, or null |
| error.code | string | yes | Stable error code |
| error.message | string | yes | Human-readable error message |
| expires_at | date-time | yes | Expiry time, or null |
| created_at | date-time | yes | Creation time |
| updated_at | date-time | yes | Last update time |
Error responses
A missing or invalid API Key returns 401 UNAUTHENTICATED.
| Code | HTTP | Meaning, trigger and action | kind | recovery | Retryable |
|---|---|---|---|---|---|
| VAULT_NOT_FOUND | 404 | Vault absent or outside this account; check the vault ID | validation_failure | none | no |
| VAULT_INVALID_STATE | 409 | Writing to an archived vault or secret; use an active resource | validation_failure | none | no |
| INVALID_PARAMS | 400 | Invalid fields, names, hosts, metadata, pagination or return URL; correct the request | validation_failure | none | no |
| RATE_LIMITED | 429 | Authorization or validation minute quota exceeded; wait for the next window | rate_limit | wait_then_retry | yes |
| OAUTH_DISCOVERY_FAILED | 400 | OAuth metadata discovery failed; check the resource URL | validation_failure | continue_from_problem | no |
| OAUTH_REGISTRATION_UNSUPPORTED | 400 | Provider does not accept automatic client registration; add credentials manually | validation_failure | continue_from_problem | no |
| OAUTH_ISSUER_MISMATCH | 400 | Authorization issuer differs from the expected issuer; check the service URL | provider_upstream | retry_from_user | no |
curl -X POST "https://api.deepraxis.ai/vault/v1/authorizations" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"vault_id\":\"${VAULT_ID}\",\"template_id\":\"linear\"}"Get authorization
GET /vault/v1/authorizations/{authorization_id}
| Parameter | Location | Description |
|---|---|---|
| authorization_id | path | ID of the authorization in your account, returned when authorization is created. |
Response
HTTP 200
application/json
| Field | Type / enum | Required | Description |
|---|---|---|---|
| id | string | yes | Object ID |
| type | "vault_authorization" | yes | Object type |
| vault_id | string | yes | Vault ID |
| status | "pending" / "authorizing" / "completed" / "failed" / "expired" | yes | Current status |
| resource | string | yes | Authorized resource URL |
| secret_name | string | yes | Associated secret name |
| connect_url | string | yes | One-time confirmation page, valid for 30 minutes |
| client_registration | "cimd" / "dcr" / null | yes | cimd: Client ID Metadata Document; dcr: Dynamic Client Registration; null before registration |
| secret_id | string / null | yes | Associated secret ID, or null |
| error | object / null | yes | Failure details, or null |
| error.code | string | yes | Stable error code |
| error.message | string | yes | Human-readable error message |
| expires_at | date-time | yes | Expiry time, or null |
| created_at | date-time | yes | Creation time |
| updated_at | date-time | yes | Last update time |
Error responses
A missing or invalid API Key returns 401 UNAUTHENTICATED.
| Code | HTTP | Meaning, trigger and action | kind | recovery | Retryable |
|---|---|---|---|---|---|
| AUTHORIZATION_NOT_FOUND | 404 | Authorization or connect link absent; start authorization again | validation_failure | none | no |
curl "https://api.deepraxis.ai/vault/v1/authorizations/${AUTHORIZATION_ID}" \
-H "Authorization: Bearer $PRAXIS_API_KEY"Get return URLs
GET /vault/v1/settings/return_urls
Response
HTTP 200
application/json
| Field | Type / enum | Required | Description |
|---|---|---|---|
| urls | string[] | yes | At most 10 HTTPS URLs, matched exactly |
Error responses
A missing or invalid API Key returns 401 UNAUTHENTICATED. No additional domain errors.
curl "https://api.deepraxis.ai/vault/v1/settings/return_urls" \
-H "Authorization: Bearer $PRAXIS_API_KEY"Set return URLs
PUT /vault/v1/settings/return_urls
Request body
| Field | Type / enum | Required | Description |
|---|---|---|---|
| urls | string[] | yes | At most 10 HTTPS URLs, matched exactly |
Response
HTTP 200
application/json
| Field | Type / enum | Required | Description |
|---|---|---|---|
| urls | string[] | yes | At most 10 HTTPS URLs, matched exactly |
Error responses
A missing or invalid API Key returns 401 UNAUTHENTICATED.
| Code | HTTP | Meaning, trigger and action | kind | recovery | Retryable |
|---|---|---|---|---|---|
| INVALID_PARAMS | 400 | Invalid fields, names, hosts, metadata, pagination or return URL; correct the request | validation_failure | none | no |
curl -X PUT "https://api.deepraxis.ai/vault/v1/settings/return_urls" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://app.example.com/connected"]}'Authorization callback
GET /vault/v1/authorizations/callback · No API Key
| Parameter | Location | Description |
|---|---|---|
| code | query | Authorization code from the provider |
| state | query | Single-use authorization state |
| error | query | Provider denial code |
| iss | query | Authorization server issuer |
Response
HTTP 200
text/html
Confirmation or result page displayed by the browser.
HTTP 302
The Location header redirects to the provider or an allowed return URL.
Error responses
| Code | HTTP | Meaning, trigger and action | kind | recovery | Retryable |
|---|---|---|---|---|---|
| OAUTH_STATE_INVALID | 400 | Callback state missing, invalid or replayed; start authorization again | validation_failure | none | no |
| OAUTH_ISSUER_MISMATCH | 400 | Authorization issuer differs from the expected issuer; check the service URL | provider_upstream | retry_from_user | no |
| OAUTH_EXCHANGE_FAILED | 502 | Provider rejected the authorization-code exchange; authorize again | provider_upstream | retry_from_user | no |
| AUTHORIZATION_EXPIRED | 410 | Authorization link expired after 30 minutes or was consumed; start again | validation_failure | retry_from_user | no |
Returns 302 when return_url is set; otherwise returns an HTTP 200 result page.
curl "https://api.deepraxis.ai/vault/v1/authorizations/callback"OAuth client metadata
GET /vault/v1/oauth/client.json · No API Key
Response
HTTP 200
application/json
| Field | Type / enum | Required | Description |
|---|---|---|---|
| client_id | string | yes | Client metadata URL |
| client_name | string | yes | Client display name |
| redirect_uris | string[] | yes | Allowed OAuth callback URLs |
| token_endpoint_auth_method | "none" | yes | Token endpoint authentication method |
| grant_types | "authorization_code" / "refresh_token"[] | no | Supported grant types |
| response_types | "code"[] | no | Supported authorization response types |
Error responses
No additional domain errors.
curl "https://api.deepraxis.ai/vault/v1/oauth/client.json"Connect page
GET /vault/v1/connect/{token} · No API Key
| Parameter | Location | Description |
|---|---|---|
| token | path | One-time token from connect_url. |
Response
HTTP 200
text/html
Confirmation or result page displayed by the browser.
HTTP 410
text/html
Confirmation or result page displayed by the browser.
Error responses
| Code | HTTP | Meaning, trigger and action | kind | recovery | Retryable |
|---|---|---|---|---|---|
| AUTHORIZATION_NOT_FOUND | 404 | Authorization or connect link absent; start authorization again | validation_failure | none | no |
| AUTHORIZATION_EXPIRED | 410 | Authorization link expired after 30 minutes or was consumed; start again | validation_failure | retry_from_user | no |
Invalid links return 404; expired or consumed links return 410, as HTML pages.
curl "https://api.deepraxis.ai/vault/v1/connect/${TOKEN}"Continue authorization
POST /vault/v1/connect/{token}/continue · No API Key
| Parameter | Location | Description |
|---|---|---|
| token | path | One-time token from connect_url. |
Response
HTTP 302
The Location header redirects to the provider or an allowed return URL.
Error responses
| Code | HTTP | Meaning, trigger and action | kind | recovery | Retryable |
|---|---|---|---|---|---|
| AUTHORIZATION_NOT_FOUND | 404 | Authorization or connect link absent; start authorization again | validation_failure | none | no |
| AUTHORIZATION_EXPIRED | 410 | Authorization link expired after 30 minutes or was consumed; start again | validation_failure | retry_from_user | no |
| OAUTH_DISCOVERY_FAILED | 400 | OAuth metadata discovery failed; check the resource URL | validation_failure | continue_from_problem | no |
curl -X POST "https://api.deepraxis.ai/vault/v1/connect/${TOKEN}/continue"Deny authorization
POST /vault/v1/connect/{token}/deny · No API Key
| Parameter | Location | Description |
|---|---|---|
| token | path | One-time token from connect_url. |
Response
HTTP 200
text/html
Confirmation or result page displayed by the browser.
HTTP 302
The Location header redirects to the provider or an allowed return URL.
Error responses
| Code | HTTP | Meaning, trigger and action | kind | recovery | Retryable |
|---|---|---|---|---|---|
| AUTHORIZATION_NOT_FOUND | 404 | Authorization or connect link absent; start authorization again | validation_failure | none | no |
| AUTHORIZATION_EXPIRED | 410 | Authorization link expired after 30 minutes or was consumed; start again | validation_failure | retry_from_user | no |
Returns 302 when return_url is set; otherwise returns an HTTP 200 result page.
curl -X POST "https://api.deepraxis.ai/vault/v1/connect/${TOKEN}/deny"Authorization
| Field | Type / enum | Required | Description |
|---|---|---|---|
| id | string | yes | Object ID |
| type | "vault_authorization" | yes | Object type |
| vault_id | string | yes | Vault ID |
| status | "pending" / "authorizing" / "completed" / "failed" / "expired" | yes | Current status |
| resource | string | yes | Authorized resource URL |
| secret_name | string | yes | Associated secret name |
| connect_url | string | yes | One-time confirmation page, valid for 30 minutes |
| client_registration | "cimd" / "dcr" / null | yes | cimd: Client ID Metadata Document; dcr: Dynamic Client Registration; null before registration |
| secret_id | string / null | yes | Associated secret ID, or null |
| error | object / null | yes | Failure details, or null |
| error.code | string | yes | Stable error code |
| error.message | string | yes | Human-readable error message |
| expires_at | date-time | yes | Expiry time, or null |
| created_at | date-time | yes | Creation time |
| updated_at | date-time | yes | Last update time |
ReturnUrls
| Field | Type / enum | Required | Description |
|---|---|---|---|
| urls | string[] | yes | At most 10 HTTPS URLs, matched exactly |