Add or change a social sign-in provider

PUT

/api/v1/social-providers/{providerSlug}

Adds or changes the social provider :providerSlug of the request's Environment. A named provider is saved under its own name (google, github, microsoft, apple); a custom OpenID Connect provider (kind oidc) under a name of the developer's choosing, at most 20 per Environment. Adding one needs client_id and the client secret, or for Apple apple_team_id, apple_key_id and apple_private_key; a custom provider also needs display_name and discovery_url. On a change, an omitted secret keeps the stored one. A custom provider's discovery document is fetched when it is added or its URL changes, through the same guard as SSO discovery, and refused unless its issuer matches the URL, it names the authorization, token and key endpoints, it supports the code flow, and it signs ID tokens with an asymmetric algorithm. A custom provider can be enabled only after a test sign-in through it has completed, which runs in the Console's browser; changing its discovery URL or its client clears that and turns it off. Send If-Match with the provider's version to refuse a change made since it was read. Each enabled provider is a sign-in method an organization's policy can narrow. Emits environment.social_provider.set, recording which settings changed, never their values.

Authentication

Bearer TokenAuthorization Option A

JWT access token. Never send alongside X-API-Key: a request carrying both is refused.

API KeyX-API-Key Option B

API key for management-tier access. Never send alongside an Authorization header: a request carrying both is refused.

Requires permission auth_settings.manageAuthentication

Change the Environment's sign-in settings. Held only when named: full access does not include it. A scoped API key must hold it as a scope; a full-access key holds every scope within its Environment except the named-only and account scopes; a developer's token needs the Console capability that covers it. A credential without it is refused with 403.

Path Parameters

providerSlugstring Required

Headers

If-Match
Optimistic-lock version of the resource. Send the `version` field returned on read; the server rejects with 409 if the row has changed since. Leave it out to skip the check; a header that names no version (not a whole number) is refused with 400 `if_match.invalid`.
X-Canopy-Environment
The id of the Environment this request acts in. Required with an account API key, which belongs to the Account and names its Environment per request; an Environment key may send it only to name its own Environment. A missing header for an account key answers `400` (`api_key.environment_required`), one naming no Environment of the key's Account `400` (`api_key.environment_not_found`), and one naming another Environment than an Environment key's own `400` (`api_key.environment_mismatch`).

Request body

application/json

kindenum Required

`google`, `github`, `microsoft` or `apple`, saved under its own name, or `oidc` for a custom OpenID Connect provider saved under the name in the path.

one of "google" · "github" · "microsoft" · "apple" · "oidc"

client_idstring Optional

The client id the provider issued for this Environment. Required when the provider is added. For Apple, the Services ID.

max length 512

client_secretstring Optional

The client secret the provider issued. Required when a provider other than Apple is added; omit it on a change to keep the stored one. Write-only.

max length 2048

apple_team_idstring Optional

Apple only: the Team ID that issues the client-secret JWT. Required when Apple is added.

max length 64

apple_key_idstring Optional

Apple only: the id of the key that signs the client-secret JWT. Required when Apple is added.

max length 64

apple_private_keystring Optional

Apple only: the `.p8` private key, PEM-encoded. Required when Apple is added; omit it on a change to keep the stored one. Write-only.

max length 8192

display_namestring Optional

Custom providers only: what the sign-in button says. Required when a custom provider is added.

max length 60

discovery_urlstring Optional

Custom providers only: the provider's OpenID Connect discovery document, normally `<issuer>/.well-known/openid-configuration`. Required when a custom provider is added.

max length 2048

scopesstring[] Optional

Custom providers only: the scopes to ask for. Must include `openid`. Defaults to `openid email profile`.

enabledboolean Optional

Whether the provider is offered as a sign-in method. A custom provider can be enabled only after a test sign-in through it has completed.

Responses

application/json

dataSocialProviderResponseDto*

application/json

errorApiErrorBodyDto*

application/json

errorApiErrorBodyDto*

application/json

errorApiErrorBodyDto*

application/json

errorApiErrorBodyDto*

application/json

errorApiErrorBodyDto*

Errors

When the request can't be completed, the response body includes a stable error code you can branch on, and a correlation_id (also sent as the X-Correlation-Id header). Quote the correlation id when you contact support: it identifies the exact request in Canopy's logs. A request refused by an authorization check answers 403 with the code authorization.denied, and its data names the denial_reason and the permission checked.

403authorization.deniedForbidden

When it happens

The credential does not hold the permission this operation checks: a scoped API key without the scope, a developer without the Console capability that covers it, or a permission granted somewhere other than the node the request targets. The error's data names the permission.

Remediation

Add the permission named in the Authentication section to the key's scopes, or ask an account administrator to grant the covering capability, then retry. For a node-scoped operation, make sure the grant reaches the node you are acting on.

Returned object

SocialProviderResponseDtoView all properties on this resource

Request

curl -X PUT "https://auth.canopy-io.com/api/v1/social-providers/value" \
  -H "If-Match: "3"" \
  -H "X-Canopy-Environment: value" \
  -H "X-API-Key: $CANOPY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "google",
    "client_id": "string",
    "client_secret": "string",
    "apple_team_id": "string",
    "apple_key_id": "string",
    "apple_private_key": "string",
    "display_name": "string",
    "discovery_url": "string",
    "scopes": [
      "string"
    ],
    "enabled": false
  }'

Response

{
  "data": {
    "slug": "google",
    "kind": "google",
    "method": "google",
    "display_name": "string",
    "client_id": "string",
    "client_secret_set": false,
    "apple_team_id": "string",
    "apple_key_id": "string",
    "apple_private_key_set": false,
    "discovery_url": "string",
    "scopes": [
      "string"
    ],
    "enabled": false,
    "verified_at": "2026-04-20T12:00:00.000Z",
    "callback_url": "https://auth.example.com/v1/identity/auth/social/google/callback",
    "version": 0,
    "created_at": "2026-04-20T12:00:00.000Z",
    "updated_at": "2026-04-20T12:00:00.000Z"
  }
}

GETList an Environment's social sign-in providers
DELETERemove a social sign-in provider

Was this page helpful?

Tell us how we can improve this guide.