Identity connections
Connect an OIDC provider or your own signer to a team, then admit its people to Spaces with grants
An identity connection lets visitors prove who they are with a sign-in system you already run. The connection admits no one by itself. A Space admits a person only through a grant that names the connection and that person’s subject.
| Type | type |
Use it when | You provide |
|---|---|---|---|
| OpenID Connect | oidc |
Your company signs people in through an OIDC provider | Issuer, client ID, and client secret |
| White-label signer | signer |
You run your own portal and sign each visitor’s identity yourself | Issuer, sign-in URL, and Ed25519 public keys |
Owners and admins create, update, and revoke connections. A connection that team members use to sign in to Spacefast can be changed or revoked only by a team owner, in the dashboard. Every team member can list them. An OAuth token needs the teams:create scope to change a connection and teams:read to list them.
Register Spacefast with your OIDC provider
To use oidc, register Spacefast in your provider first as a web app with a client secret. Use these values:
| Setting | Value |
|---|---|
| Redirect URI | https://api.spacefast.com/identity/callback |
| Grant type | Authorization code. Spacefast also sends a PKCE S256 challenge and a nonce |
| Client authentication | HTTP Basic (client_secret_basic) |
| Scopes | openid email profile |
| ID token algorithms | RS256, PS256, ES256, or EdDSA |
Spacefast reads <issuer>/.well-known/openid-configuration over HTTPS. The issuer value in that document must match the issuer you enter. If your tenant sets presentation.accessHandoffOrigin, the redirect URI is /identity/callback on that origin instead. See Partner API configuration.
Add a connection in the dashboard
- Open the team and go to Team settings → Access.
- In SSO Providers, press Add Identity Provider. The Add SSO Provider dialog opens.
- Pick a Connection type: OpenID Connect or White-label signer.
- Enter a Name and the Issuer.
- For OpenID Connect, enter the Client ID and Client secret.
- For a signer, enter the Sign-in URL. Add the Ed25519 public keys, one
kid:base64url-keyper line. - Press Add Connection.
The connection appears as a row with an OIDC or Signer badge and its issuer.
Add a connection with the API or CLI
Send createTeamIdentityConnection:
curl "https://api.spacefast.com/v1/teams/$TEAM_ID/identity-connections" \
-H "Authorization: Bearer $SPACEFAST_API_KEY" \
-H "Content-Type: application/json" \
-d '{"type":"oidc","name":"Acme SSO","issuer":"https://login.example.com","clientId":"<client-id>","clientSecret":"<client-secret>"}'
A signer body uses authorizeUrl and publicKeys instead of the client fields:
{
"type": "signer",
"name": "Customer portal",
"issuer": "https://portal.example.com",
"authorizeUrl": "https://portal.example.com/spacefast/authorize",
"publicKeys": [{ "kid": "2026-01", "publicKey": "<43-character-base64url-key>" }]
}
The 201 response holds the connection. Its id starts with acn_, and grants use that ID. A team can have one active connection per issuer. A second one fails with 409 identity_connection_issuer_exists. From a terminal, run sf share identity create. See sf share.
| Field | Applies to | Rules |
|---|---|---|
type |
Both | oidc or signer |
name |
Both | 1 to 200 characters |
issuer |
Both | An absolute HTTPS URL, up to 1,024 characters. No user info and no fragment. Spacefast removes trailing slashes |
clientId |
oidc |
Up to 512 characters |
clientSecret |
oidc |
Up to 2,048 characters. Write-only. Responses show only clientSecretSet |
authorizeUrl |
signer |
An absolute HTTPS URL, up to 2,048 characters. No user info and no fragment |
publicKeys |
signer |
1 to 5 entries of kid and publicKey. Each kid is unique and up to 64 characters. publicKey is a raw Ed25519 public key, base64url, 43 characters |
sessionTtlSeconds |
Both | Optional. oidc: 60 to 86,400, default 28,800. signer: 60 to 1,800, default 1,800 |
Admit people to a Space
The connection proves identity. A grant on the Space decides what that identity can open.
To add a grant in the dashboard, open the Space and go to Share. Open Advanced, then find SSO and Identity. Pick the Connection, then fill in Subject, Name, Paths, and an optional Expires. Choose What this identity can do and press Add Identity Grant. If the team has no connection, the card shows No SSO Provider.
From a terminal, run sf share identity grant:
sf share identity grant --connection acn_xxxxxxxx --subject alex@example.com --name "Alex (Acme SSO)" --path '/docs/**' --space my-site
Over HTTP, send createSpaceGrant with an external audience:
{
"name": "Alex (Acme SSO)",
"audience": { "kind": "external", "connectionId": "acn_xxxxxxxx", "subject": "alex@example.com" },
"resources": { "include": ["/docs/**"] },
"capabilities": ["page.view"],
"target": { "kind": "live" }
}
- The subject must equal the
subclaim. Spacefast compares it exactly. It holds up to 255 characters. - A name is required. Spacefast stores the subject as a hash, so the grant list cannot show it.
- The connection must belong to the Space’s team. The Space must be claimed.
- Verified email follows the provider. A grant that requires a verified email admits an OIDC visitor only when the ID token has
email_verified: true. A signer proof never counts as a verified email.
Roles, paths, and targets work as they do for every other grant. See Spacefast Share.
A visitor who cannot open a page sees the Space’s access page. It shows Continue with and the connection name for each connection that an active grant on that Space trusts. A connection with no grant on the Space does not appear there.
Build a signer
A signer connection lets your portal prove a visitor’s identity with an Ed25519 key registered on the connection. The proof’s subject must match the subject on a Space grant. A signer proof lives at most 30 minutes, and never longer than the connection’s session lifetime.
The proof-exchange protocol is not part of the public API reference. Contact support@spacefast.com for the current integration steps.
Update a connection
In SSO Providers, press Update on the connection’s row.
| Type | Fields | Button |
|---|---|---|
| OpenID Connect | Client ID, Replacement client secret, Session lifetime in minutes | Update Connection |
| White-label signer | Replacement Ed25519 key set, Session lifetime in minutes | Rotate Key Set |
Leave Replacement client secret blank to keep the current secret. To rename a connection or change a signer’s sign-in URL, use the API or the CLI.
updateTeamIdentityConnection accepts name, clientId, clientSecret, authorizeUrl, publicKeys, and sessionTtlSeconds. It accepts sessionTtlSeconds from 60 to 86,400. For a signer, Spacefast lowers any value above 1,800 to 1,800. publicKeys replaces the whole key set. The type and issuer cannot change.
Grants that use the connection survive rotation. Changing the client ID, client secret, key set, or session lifetime ends sessions admitted through the connection, so those visitors sign in again. Renaming a connection does not end sessions.
To keep both signing keys valid during a transition:
- Send a key set that holds the old key and the new key.
- Sign new proofs with the new key.
- Send a key set that holds only the new key.
Replace a connection
A team can have one active connection per issuer. Revoking a connection also revokes its grants. Plan the order:
- To move to a new issuer, create the new connection and its grants first. Then revoke the old connection.
- To change the type for the same issuer, revoke the old connection first, because the new one uses the same issuer. Then create the new connection and add its grants again. Visitors cannot sign in through that issuer until the new grants exist.
Revoke a connection
Press Revoke on the row, then Revoke Connection in the dialog. Over HTTP, send revokeTeamIdentityConnection. It answers 204. From a terminal, run sf share identity revoke.
Revoking removes the grants too. Spacefast revokes every grant on the team’s Spaces that trusts the connection’s issuer, then the connection itself. If team members sign in to Spacefast through the connection, revoking it also turns member sign-in off.
A revoked connection stays in listTeamIdentityConnections with revokedAt set. It cannot be updated. To restore access, create a new connection and add its grants again.
Errors
| Code | Status | Meaning |
|---|---|---|
identity_connection_invalid_issuer |
422 | The issuer is not an absolute HTTPS URL, or it holds user info or a fragment |
identity_connection_invalid_authorize_url |
422 | The sign-in URL is not an absolute HTTPS URL, or it holds user info or a fragment |
identity_connection_duplicate_kid |
422 | Two signer keys share a kid |
identity_connection_type_mismatch |
422 | An update sent signer fields to an OIDC connection, or OIDC fields to a signer |
validation_error |
422 | The body failed the schema, or an external grant has no name |
not_found |
404 | The connection does not exist, belongs to another team, or is revoked |
forbidden |
403 | Your role cannot change connections, or a signer proof was rejected |
team_owner_required |
403 | Team members sign in to Spacefast through this connection, so only an owner can change it, in the dashboard |
identity_connection_issuer_exists |
409 | The team already has an active connection for that issuer |
OIDC sign-in failures show to the visitor during the round trip:
| Code | Status | Meaning |
|---|---|---|
oidc_discovery_failed |
503 or 422 | The discovery document did not load, or it is not valid |
oidc_discovery_issuer_mismatch |
422 | The discovery document names a different issuer |
oidc_token_exchange_rejected |
422 | The provider refused the authorization code or the client credentials |
oidc_issuer_mismatch |
422 | The ID token iss does not match the connection |
oidc_audience_mismatch |
422 | The ID token aud does not include the client ID |
oidc_state_expired |
422 | The sign-in took longer than 10 minutes. Start again |