Add OAuth Provider
POST
/v1/endpoints/{uuid}/oauth/providers
Attach a new OAuth identity provider to an endpoint. Once attached and enabled, when the endpoint's auth mode is sso (stored as basic with the oauth_sso method on), visitors can sign in via this provider before reaching the upstream agent.
Each endpoint can have at most one provider per provider_type — uploading a second google provider returns 409. Use /oauth/presets to fetch canonical auth_url / token_url / user_info_url values for known providers (Google, GitHub, Microsoft, Okta, Auth0).
The client_secret is encrypted at rest with the platform's cert encryption key and never returned in any read endpoint. To rotate, call update with a fresh client_secret.
Every login uses PKCE (RFC 7636, S256) automatically — no configuration needed. Set issuer (below) to additionally verify the OIDC id_token at the edge.
Strict JSON decoding — unknown body fields return 400.
Path parameters
Request body
One of google, github, azure, okta, auth0, custom. Anything else returns 400.
Display label shown on the login page ("Sign in with Google").
Client ID issued by the IdP when you registered your app.
Client secret. Encrypted at rest; never returned by GET endpoints.
OAuth authorization endpoint (e.g.
https://accounts.google.com/o/oauth2/v2/auth). Must be
https and resolve to a public IP (SSRF guard). Use
/oauth/presets for known providers.
Token-exchange endpoint. Must be https and resolve to a public IP.
User-info endpoint. Required for OIDC flows; some providers encode the user identity in the access token instead (skip in that case). When set, must be https and resolve to a public IP.
Comma-separated OAuth scopes. Common: Google openid,email,profile, GitHub read:user,user:email.
Which user-info JSON field to use as the canonical identifier (email, sub, login).
OIDC issuer (e.g. https://accounts.google.com). When set, the edge cryptographically verifies the id_token returned by the token exchange — signature (alg-pinned RS/ES/PS), exp, iss and aud — instead of trusting the user-info endpoint. Must be https and resolve to a public IP. Leave empty to keep the classic user-info flow.
JWKS endpoint for id_token signature keys. Optional — when omitted it is discovered from <issuer>/.well-known/openid-configuration (cached ~1h). Must be https and resolve to a public IP. Only consulted when issuer is set.
true = visible on the login page right away; false = saved but hidden.
Response (201 Created)
The newly-created provider with its assigned uuid (and endpoint_uuid); client_secret is omitted from the response; has_client_secret says whether one is stored.
Deprecated: until the sunset this response also carries the legacy integer id and *_id fields. Don't use them; read uuid and the *_uuid fields.
Errors
Unknown body fields (strict decoding), missing required field, invalid provider_type, or a provider URL that isn't https / resolves to a private IP.
Caller lacks the endpoints:write permission in the active account.
Endpoint doesn't exist or doesn't belong to the calling account.
A provider of the same provider_type already exists on this endpoint.
Crypto error encrypting the secret, or database error.
curl -X POST "https://api.ngris.com/v1/endpoints/<uuid>/oauth/providers" \
-H "X-API-KEY: <your_api_key>" \
-H "Content-Type: application/json" \
-d '{
"provider_type": "google",
"provider_name": "Sign in with Google",
"client_id": "1234567890-abc.apps.googleusercontent.com",
"client_secret": "GOCSPX-...",
"auth_url": "https://accounts.google.com/o/oauth2/v2/auth",
"token_url": "https://oauth2.googleapis.com/token",
"user_info_url": "https://www.googleapis.com/oauth2/v2/userinfo",
"scopes": "openid,email,profile",
"identifier_field": "email",
"enabled": true
}'
from ngris import Ngris
client = Ngris(api_key="<your_api_key>")
client.endpoint_oauth.create_provider("<endpoint_uuid>", {
"provider_type": "google",
"provider_name": "Sign in with Google",
"client_id": "...",
"client_secret": "GOCSPX-...",
"auth_url": "https://accounts.google.com/o/oauth2/v2/auth",
"token_url": "https://oauth2.googleapis.com/token",
"user_info_url": "https://www.googleapis.com/oauth2/v2/userinfo",
"scopes": "openid,email,profile",
"identifier_field": "email",
"enabled": True,
})
{
"uuid": "019b407c-8a46-7001-897f-343e36ba8939",
"endpoint_uuid": "019bb1e4-e785-77d2-9966-c3cff31d0a0e",
"provider_type": "google",
"provider_name": "Sign in with Google",
"client_id": "1234567890-abc.apps.googleusercontent.com",
"auth_url": "https://accounts.google.com/o/oauth2/v2/auth",
"token_url": "https://oauth2.googleapis.com/token",
"user_info_url": "https://www.googleapis.com/oauth2/v2/userinfo",
"scopes": "openid,email,profile",
"identifier_field": "email",
"enabled": true,
"has_client_secret": true,
"created_at": "2026-04-01T00:00:00Z",
"updated_at": "2026-04-01T00:00:00Z"
}