Skip to main content
POST
Connect a GitHub installation to the workspace

Authorizations

Authorization
string
header
required

WorkOS access JWT or a user-owned WorkOS API key. User keys are bound to one organization and restricted to their enabled product permissions. Session-only onboarding and session revocation require an interactive access JWT. No cookie session is assumed.

Headers

X-Request-Id
string

Optional caller-provided correlation identifier.

Required string length: 1 - 128
Idempotency-Key
string
required

Identifies one mutation and its canonical request payload.

Required string length: 1 - 128

Path Parameters

organization_id
string
required
Pattern: ^[0-9A-HJKMNP-TV-Z]{26}$

Body

application/json

The body is of type object.

Response

Bound authorization handoff, replay status, or the existing connection.

authorization_id
string | null
required
Pattern: ^[0-7][0-9A-HJKMNP-TV-Z]{25}$
status
enum<string>
required
Available options:
pending,
authorizing,
connected,
failed,
expired
last_failure
enum<string> | null
required
Available options:
installation_access_required,
account_admin_required,
authorization_code_rejected,
provider_unavailable,
expired,
session_inactive,
denied,
code_spent,
state_unknown,
null
authorization_url
string<uri> | null
required

One GitHub browser authorization link when pending; contains only the bound single-use state, never a provider credential.

expires_at
string<date-time> | null
required
connection
object | null
required