# Yoursafe ID Endpoint Reference

Exact endpoint references for integrating OAuth 2.0 / OpenID Connect with Yoursafe Identity Services: discovery, authorization and device flows, token issuance, `userinfo`, JWT introspection and revocation, logout, and JWKS. Always treat the live{" "} [discovery document](#discovery) as authoritative for URLs and supported metadata.

## Discovery metadata

### GET `https://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

### GET `https://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

### POST `https://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](#token) 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

### PUT `https://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 using `client_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

### GET `https://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](/en/id-claims-glossary).

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

## Token introspection

### POST `https://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

### POST `https://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)

### GET `https://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

### GET `https://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).

Next: [Overview](/en/identity-services)

Choose another guide from the Identity Services overview.