Add OAuth Provider
Attach a new OAuth identity provider to an endpoint. Once attached and enabled, when the endpoint's auth mode is oauth or oidc, 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
endpoint_id string (uuid) Req
Endpoint UUID.
Request body
provider_type string Req
One of
google, github, azure, okta, auth0, custom. Anything else returns 400.provider_name string Req
Display label shown on the login page (
"Sign in with Google").client_id string Req
Client ID issued by the IdP when you registered your app.
client_secret string Req
Client secret. Encrypted at rest; never returned by GET endpoints.
auth_url string Req
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_url string Req
Token-exchange endpoint. Must be https and resolve to a public IP.
user_info_url string
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.
scopes string
Comma-separated OAuth scopes. Common: Google
openid,email,profile, GitHub read:user,user:email.identifier_field string
Which user-info JSON field to use as the canonical identifier (
email, sub, login).issuer string
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_url string
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.enabled boolean
true = visible on the login page right away; false = saved but hidden.Response (201 Created)
The newly-created provider with assigned id; client_secret is omitted from the response.
Errors
400 Bad Request
Unknown body fields (strict decoding), missing required field, invalid
provider_type, or a provider URL that isn't https / resolves to a private IP.401 Unauthorized
Missing auth.
403 Forbidden
Caller lacks the
endpoints:write permission in the active account.404 Not Found
Endpoint doesn't exist or doesn't belong to the calling account.
409 Conflict
A provider of the same
provider_type already exists on this endpoint.500
Crypto error encrypting the secret, or database error.
Request — Google
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
}'
Python
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,
})
Response — 201 Created
{
"id": 1,
"endpoint_id": 184,
"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,
"created_at": "2026-04-01T00:00:00Z",
"updated_at": "2026-04-01T00:00:00Z"
}