Register an app
const url = 'https://example.com/v1/connection-apps';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"app":"example","label":"example","oauth2":{"clientId":"example","clientSecret":{"envName":"example","name":"example"},"tenant":"example"},"githubApp":{"appNumber":1,"slug":"example","clientId":"example","clientSecret":{"envName":"example","name":"example"},"privateKey":{"envName":"example","name":"example"},"webhookSecret":{"envName":"example","name":"example"}},"projects":["example"]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/v1/connection-apps \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "app": "example", "label": "example", "oauth2": { "clientId": "example", "clientSecret": { "envName": "example", "name": "example" }, "tenant": "example" }, "githubApp": { "appNumber": 1, "slug": "example", "clientId": "example", "clientSecret": { "envName": "example", "name": "example" }, "privateKey": { "envName": "example", "name": "example" }, "webhookSecret": { "envName": "example", "name": "example" } }, "projects": [ "example" ] }'Registers the workspace’s own client at an app. Store its secrets first; the registration references them by name. The response gives the redirectUrl and noticesUrl to enter at the app. Tenant admins only.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Header Parameters
Section titled “Header Parameters”Caller-supplied idempotency key, scoped to the caller: the same key from someone else in the workspace is their own request (from 0.1.5). Retries with the same key return the original response byte-identical (per docs/API-ROUTE-CONVENTIONS.md §3.1). A retry sent while the first request still runs is answered 409 idempotency-key-in-flight with Retry-After, on a runtime whose store holds keys (from 0.1.5); retry after it, and you get the first request’s answer. An answer that carries a secret (a new API key or public run token, a session token, a generated signing secret) isn’t kept: a retry gets 409 idempotency-key-replay-withheld, with the first request’s status and when it succeeded (from 0.1.5). A request whose key store can’t be read before it runs is answered 503 idempotency-store-unavailable with Retry-After: nothing ran, so retry with the same key (from 0.3.0).
Request Bodyrequired
Section titled “Request Bodyrequired”Give oauth2 for an app that signs in with OAuth, githubApp for a GitHub App.
object
The app’s entry id.
object
A secret by name in the deployment’s secrets store, resolved at tenant scope. The registration keeps only this reference, never the value.
object
The directory the app signs people in at, for an app whose sign-in names one: Microsoft’s tenant id or domain for a single-tenant app, organizations, common or consumers for a multi-tenant one. Required when the app’s entry has no default, refused for an app without one (connection-app-invalid, details.field oauth2.tenant).
object
The app’s slug.
A secret by name in the deployment’s secrets store, resolved at tenant scope. The registration keeps only this reference, never the value.
object
A secret by name in the deployment’s secrets store, resolved at tenant scope. The registration keeps only this reference, never the value.
object
A secret by name in the deployment’s secrets store, resolved at tenant scope. The registration keeps only this reference, never the value.
object
The projects whose runs may use its connections. Leave out for every project.
Examplegenerated
{ "app": "example", "label": "example", "oauth2": { "clientId": "example", "clientSecret": { "envName": "example", "name": "example" }, "tenant": "example" }, "githubApp": { "appNumber": 1, "slug": "example", "clientId": "example", "clientSecret": { "envName": "example", "name": "example" }, "privateKey": { "envName": "example", "name": "example" }, "webhookSecret": { "envName": "example", "name": "example" } }, "projects": [ "example" ]}Responses
Section titled “Responses”App registered.
A workspace’s registration of its own client at an app. Secrets are references, never values.
object
The app’s entry id.
object
A secret by name in the deployment’s secrets store, resolved at tenant scope. The registration keeps only this reference, never the value.
object
The directory the app signs people in at, for an app whose sign-in names one: Microsoft’s tenant id or domain for a single-tenant app, organizations, common or consumers for a multi-tenant one. Required when the app’s entry has no default, refused for an app without one (connection-app-invalid, details.field oauth2.tenant).
object
The app’s slug.
A secret by name in the deployment’s secrets store, resolved at tenant scope. The registration keeps only this reference, never the value.
object
A secret by name in the deployment’s secrets store, resolved at tenant scope. The registration keeps only this reference, never the value.
object
A secret by name in the deployment’s secrets store, resolved at tenant scope. The registration keeps only this reference, never the value.
object
The projects whose runs may use its connections. Absent: every project.
Give this to the app as its redirect URL: a GitHub App’s Callback URL, with “Request user authorization (OAuth) during installation” ticked.
Give this to the app as the place it reports removals.
Examplegenerated
{ "appId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "app": "example", "label": "example", "oauth2": { "clientId": "example", "clientSecret": { "envName": "example", "name": "example" }, "tenant": "example" }, "githubApp": { "appNumber": 1, "slug": "example", "clientId": "example", "clientSecret": { "envName": "example", "name": "example" }, "privateKey": { "envName": "example", "name": "example" }, "webhookSecret": { "envName": "example", "name": "example" } }, "projects": [ "example" ], "redirectUrl": "https://example.com", "noticesUrl": "https://example.com", "createdAt": "2026-04-15T12:00:00Z", "updatedAt": "2026-04-15T12:00:00Z", "removedAt": "2026-04-15T12:00:00Z"}Malformed body or unknown field (bad-input, details.field); a registration that doesn’t fit its entry, or that would serve a project another registration of the app serves (connection-app-invalid, details.field); no such app (connection-app-unknown-entry); a model provider’s key named as a secret (provider-key-refused); or a secret under the reserved kindgi. prefix (reserved-name-prefix).
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}Missing / malformed / expired / revoked bearer token.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}Not a tenant admin (permission-denied).
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}Idempotency-Key was reused with a different body, or resource-state conflict. Or env-not-served: this runtime keeps every value under the env it serves (whoami’s servedEnv, with refusesOtherEnvs), and the secret reference names another. Name it under details.servedEnv. Nothing is stored.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}The request body is over the API’s limit (request-too-large; details.maxBytes says how much).
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}Server error (unmapped domain code or framework crash).
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}The Idempotency-Key store couldn’t be read before the request ran (idempotency-store-unavailable), so nothing was changed; Retry-After (whole seconds) says when to try again with the same key.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}See also
GET /v1/connection-apps: List the workspace's app registrations- Error code
bad-input - Error code
connection-app-invalid - Error code
connection-app-unknown-entry - Error code
env-not-served - Error code
idempotency-store-unavailable - Error code
permission-denied - Error code
provider-key-refused - Error code
request-too-large - Error code
reserved-name-prefix - Every error code