Yoursafe · Yoursafe ID
Yoursafe

Yoursafe ID endpoint reference

OpenAPI

OAuth 2.0 / OpenID Connect on accounts.yoursafe.com: discovery, authorization and device flows, token issuance, userinfo, introspection and revocation, logout, and JWKS. Treat the live discovery document as authoritative for URLs and metadata.

Discovery metadata

GEThttps://accounts.yoursafe.com/.well-known/openid-configuration

OIDC discovery metadata.

Request

No request parameters or authentication required.

GET https://accounts.yoursafe.com/.well-known/openid-configuration
Response

OpenID Provider metadata JSON. The sample below is abbreviated; ... marks omitted keys (for example full auth-method arrays, PKCE, subject types). Use the live document for complete URLs and supported values—this page documents each major endpoint separately.

{ "issuer": "https://accounts.yoursafe.com", "authorization_endpoint": "https://accounts.yoursafe.com/oauth2/authorize", "device_authorization_endpoint": "https://accounts.yoursafe.com/oauth2/device_authorization", "token_endpoint": "https://accounts.yoursafe.com/oauth2/token", "jwks_uri": "https://accounts.yoursafe.com/oauth2/jwks", "userinfo_endpoint": "https://accounts.yoursafe.com/userinfo", "end_session_endpoint": "https://accounts.yoursafe.com/connect/logout", "revocation_endpoint": "https://accounts.yoursafe.com/oauth2/revoke", "introspection_endpoint": "https://accounts.yoursafe.com/oauth2/introspect", "response_types_supported": ["code"], "grant_types_supported": ["authorization_code"], "id_token_signing_alg_values_supported": ["RS256"], ... "scopes_supported": ["openid", "default", "profile", "platform"] }

Authorize

GEThttps://accounts.yoursafe.com/oauth2/authorize

Start user authentication and consent.

Request

Query parameters: response_type=code, client_id, redirect_uri, scope, state, and nonce.

GET https://accounts.yoursafe.com/oauth2/authorize ?response_type=code &client_id=your_client_id &redirect_uri=https%3A%2F%2Fexample.com%2Fauth%2Fcallback &scope=openid%20default &state=random_state_value &nonce=random_nonce_value
Response

Browser redirect (not JSON):

  • Success: redirect_uri?code=...&state=...
  • Error: redirect_uri?error=...&error_description=...&state=...

Device authorization

POSThttps://accounts.yoursafe.com/oauth2/device_authorization

Start the OAuth 2.0 Device Authorization Grant (RFC 8628) for clients without a browser or with limited input—smart TVs, CLIs, and similar.

Request

application/x-www-form-urlencoded body:client_id, scope; confidential clients authenticate per metadata using client_secret_basic or client_secret_post as advertised under token_endpoint_auth_methods_supported.

POST https://accounts.yoursafe.com/oauth2/device_authorization Content-Type: application/x-www-form-urlencoded client_id=your_client_id scope=openid%20default
Response

JSON with device_code, user_code, verification URIs, expires_in, and polling interval. The user completes login at the verification URL; your client polls the token endpoint with grant_type=urn:ietf:params:oauth:grant-type:device_code.

{ "device_code": "GmRhmhcxhwAzkoEqiMEG_DewAEKNEWExample", "user_code": "WDJB-MJHT", "verification_uri": "https://accounts.yoursafe.com/device", "verification_uri_complete": "https://accounts.yoursafe.com/device?user_code=WDJB-MJHT", "expires_in": 1800, "interval": 5 }

Token exchange

PUThttps://accounts.yoursafe.com/oauth2/token

Exchange authorization code for tokens. Yoursafe docs specify PUT.

Request

Authorization Code grant parameters:grant_type=authorization_code, code,redirect_uri; plus client authentication usingclient_id and client_secret (or another method allowed by provider metadata).

PUT https://accounts.yoursafe.com/oauth2/token Content-Type: application/x-www-form-urlencoded grant_type=authorization_code code=SplxlOBeZQQYbYS6WxSbIA redirect_uri=https%3A%2F%2Fexample.com%2Fauth%2Fcallback client_id=your_client_id client_secret=your_client_secret
Response

Yoursafe→Your backend

JSON token response body, typically:

{ "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...", "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjEiLCJ0eXAiOiJKV1QifQ...", "token_type": "Bearer", "expires_in": 1800, "scope": "openid default" }

May also include refresh_token depending on client and provider configuration.

The same endpoint completes the device-code grant when grant_type=urn:ietf:params:oauth:grant-type:device_code, device_code, and client_id are supplied (plus client authentication if required).

UserInfo

GEThttps://accounts.yoursafe.com/userinfo

Retrieve OpenID Connect claims for the authenticated subject using a valid access token (often in addition to the ID token).

Request

Pass the access token from the token response as a Bearer token. Scopes granted at authorize time determine which claims are available.

GET https://accounts.yoursafe.com/userinfo Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Response

JSON object with claim names and values (for example sub and scope-dependent fields). For claim semantics by scope, see Claims Glossary.

{ "sub": "248289761001", ... }

Token introspection

POSThttps://accounts.yoursafe.com/oauth2/introspect

RFC 7662 introspection: ask the authorization server whether a token is active and retrieve metadata (client, scope, expiry), for resource servers or backends that validate opaque or remote tokens.

Request

application/x-www-form-urlencoded with token and optional token_type_hint (access_token or refresh_token). Authenticate the client using a method allowed by introspection_endpoint_auth_methods_supported in discovery (typically client_secret_basic or client_secret_post).

POST https://accounts.yoursafe.com/oauth2/introspect Content-Type: application/x-www-form-urlencoded Authorization: Basic base64(client_id:client_secret) token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9... &token_type_hint=access_token
Response

JSON object; inactive or unknown tokens yield "active": false (per RFC 7662). Active tokens include fields such as scope, client_id, exp, and sub when applicable.

{ "active": true, "scope": "openid default", "client_id": "your_client_id", "sub": "248289761001", "exp": 1735689600 }

Token revocation

POSThttps://accounts.yoursafe.com/oauth2/revoke

RFC 7009 revocation: invalidate a refresh or access token so it can no longer be used (for example on sign-out or credential rotation).

Request

application/x-www-form-urlencoded with token and optional token_type_hint. Client authentication as in discovery revocation_endpoint_auth_methods_supported.

POST https://accounts.yoursafe.com/oauth2/revoke Content-Type: application/x-www-form-urlencoded client_id=your_client_id &client_secret=your_client_secret &token=REFRESH_OR_ACCESS_TOKEN &token_type_hint=refresh_token
Response

Empty body with 200 OK on success; invalid or unknown tokens are often accepted without error per RFC 7009.

End session (RP-initiated logout)

GEThttps://accounts.yoursafe.com/connect/logout

OpenID Connect RP-Initiated Logout: end the session at Yoursafe and optionally return the user to your app. URL and parameters are advertised as end_session_endpoint in discovery.

Request

Typical query parameters: id_token_hint (issued ID token),post_logout_redirect_uri (must match a registered URI), client_id, and optional state. Exact requirements follow provider configuration and the discovery document.

GET https://accounts.yoursafe.com/connect/logout ?id_token_hint=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9... &post_logout_redirect_uri=https%3A%2F%2Fexample.com%2F &client_id=your_client_id
Response

Browser navigation: clears the OP session and redirects to post_logout_redirect_uri when allowed; otherwise a confirmation or error page.

JWKS

GEThttps://accounts.yoursafe.com/oauth2/jwks

Public signing keys for JWT verification.

Request

No request body or authentication required.

GET https://accounts.yoursafe.com/oauth2/jwks
Response

JWKS JSON (keys array with RSA public key material).