Skip to content
Esc
↑↓navigate↵open⌘Jpreview
On this page

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

  1. Open the team and go to Team settings → Access.
  2. In SSO Providers, press Add Identity Provider. The Add SSO Provider dialog opens.
  3. Pick a Connection type: OpenID Connect or White-label signer.
  4. Enter a Name and the Issuer.
  5. For OpenID Connect, enter the Client ID and Client secret.
  6. For a signer, enter the Sign-in URL. Add the Ed25519 public keys, one kid:base64url-key per line.
  7. 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 sub claim. 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:

  1. Send a key set that holds the old key and the new key.
  2. Sign new proofs with the new key.
  3. 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

Last updated on

Was this page helpful?