> Agent-readable docs index: /llms.txt. Download /docs.zip to grep all markdown files locally.

---
title: "OAuth & OpenID"
description: "Use Neverlose as an OAuth 2.0 authorization server and OpenID Connect identity provider."
icon: key-round
---

# OAuth & OpenID

Neverlose supports OAuth authorization and can act as an OpenID Connect identity
provider.

## Identity Provider

<Columns cols={3}>
  <Card title="OAuth 2.0" icon="key-round" href="https://oauth.net/2" arrow>
    Authorization code flow for application login.
  </Card>

  <Card title="OpenID Connect Core" icon="id-card" href="https://openid.net/specs/openid-connect-core-1_0.html" arrow>
    ID token format and identity claims.
  </Card>

  <Card title="Discovery" icon="radar" href="https://openid.net/specs/openid-connect-discovery-1_0.html" arrow>
    Metadata for authorization, token, userinfo, and JWKS endpoints.
  </Card>
</Columns>

Client IDs are issued manually. If you need one, please open a new support ticket and describe your use-case, we will gladly register your app if it meets our guidelines.

## Endpoints

<Card title="OIDC discovery URI" icon="compass" href="https://neverlose.cc/.well-known/openid-configuration" arrow>
  Use the discovery document for current authorization, token, userinfo, JWKS, and supported parameter metadata.
</Card>

## ID Token Contents

<Note>
  Previously, our idP was not fully OIDC compliant because it was not providing an `id_token`. This is now fixed.
</Note>

<Tabs>
  <Tab title="Core Claims" icon="badge-check">
    <ParamField body="iss" type="string" required>
      Issuer, always `https://neverlose.cc`.
    </ParamField>

    <ParamField body="iat" type="integer" required>
      Issued at, timestamp of token creation.
    </ParamField>

    <ParamField body="exp" type="integer" required>
      Expiration timestamp, same as access token lifetime.
    </ParamField>

    <ParamField body="sub" type="string" required>
      Subject, user ID, same as in userinfo endpoint.
    </ParamField>
  </Tab>

  <Tab title="Client Claims" icon="app-window">
    <ParamField body="aud" type="string" required>
      Audience, `client_id` of your app.
    </ParamField>

    <ParamField body="nonce" type="string">
      Nonce provided when redirecting user to authorization endpoint.
    </ParamField>

    <ParamField body="at_hash" type="string">
      Hash of `access_token` as specified in OIDC spec.
    </ParamField>
  </Tab>
</Tabs>

ID Token is signed with key provided at `jwks_uri` in openid-configuration.

## OAuth Behavior

<AccordionGroup>
  <Accordion title="Flow" icon="workflow" defaultOpen>
    Supported **response types**: `code`. Supported **grant types**: `authorization_code`.
  </Accordion>

  <Accordion title="Refresh tokens" icon="rotate-ccw">
    Refresh tokens are **NEVER** issued. Access token expire time is set per client and cannot be adjusted at request.
  </Accordion>

  <Accordion title="State" icon="shield">
    The `state` parameter is required unless `no_state` is in scope.
  </Accordion>

  <Accordion title="PKCE" icon="lock-keyhole">
    PKCE (`code_challenge`) is required unless you have a good reason to not implement it.
    `no_pkce` will not work unless you are permitted to use it. `S256` is the only supported challenge method.
  </Accordion>
</AccordionGroup>

## Supported OAuth Scopes

<Columns cols={2}>
  <Card title="profile" icon="user">
    Read access to user's login and profile picture.
  </Card>

  <Card title="email" icon="mail">
    Read access to user's email.
  </Card>

  <Card title="openid" icon="id-card">
    Required to access OIDC endpoints.
  </Card>

  <Card title="no_state / no_pkce" icon="shield-alert">
    Special permission scopes for omitting state or PKCE.
  </Card>
</Columns>

## Supported OpenID Userinfo Claims

<Tabs>
  <Tab title="Identity" icon="id-card">
    | Field                  | Content                                           | Scope needed |
    | ---------------------- | ------------------------------------------------- | ------------ |
    | `sub`                  | Numeric user ID presented as string per OIDC spec | `openid`     |
    | `preferred_username`   | User's login                                      | `profile`    |
    | `name`                 | User's login                                      | `profile`    |
    | `cc.neverlose.user_id` | User ID presented as integer                      | `openid`     |
    | `cc.neverlose.login`   | User's login                                      | `profile`    |
  </Tab>

  <Tab title="Profile" icon="image">
    | Field                   | Content                                  | Scope needed |
    | ----------------------- | ---------------------------------------- | ------------ |
    | `profile`               | URL to user's profile (forum)            | `profile`    |
    | `picture`               | URL to user's profile picture (PNG)      | `profile`    |
    | `cc.neverlose.reg_date` | Registration date in `YYYY-MM-DD` format | `profile`    |
  </Tab>

  <Tab title="Email" icon="mail">
    | Field   | Content      | Scope needed |
    | ------- | ------------ | ------------ |
    | `email` | User's email | `email`      |
  </Tab>
</Tabs>
