> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nemu.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth 2.0

> Authorize apps to act on an account and read the user who approved access

## Overview

We are an OAuth 2.0 provider. Your app sends a user to us, they approve the access you asked
for, and we hand back a bearer token. Your app uses that token to call the API on behalf of
that user.

This is the same model as "Login with GitHub". It is OAuth 2.0, not OpenID Connect, so there
is no `id_token`. To read the identity of the user who approved access, call `GET
/api/v1/user` with the `profile:read` scope.

<CardGroup cols={2}>
  <Card title="Quickstart" href="/oauth/quickstart">
    Go from a registered app to a logged in user and their profile in a few minutes.
  </Card>

  <Card title="Authorization code" href="/oauth/authorization_code">
    The full user consent flow with PKCE for apps acting on behalf of a user.
  </Card>

  <Card title="Client credentials" href="/oauth/client_credentials">
    A server to server flow for your own backend, with no user prompt.
  </Card>

  <Card title="Scopes" href="/oauth/scopes">
    Every scope you can request and what each one grants.
  </Card>

  <Card title="Versioning" href="/oauth/versioning">
    Dated API versions, the version header, and how to pin a version.
  </Card>

  <Card title="Endpoints" href="/oauth/reference">
    The token and authorize endpoints that issue and refresh tokens.
  </Card>
</CardGroup>

## Which flow do I use

<CardGroup cols={2}>
  <Card title="Acting for a user">
    A third party app where people sign in with their own account. Use the
    [authorization code flow](/oauth/authorization_code). Register a Web application.
  </Card>

  <Card title="Acting for yourself">
    Your own backend using your own account, with no other users. Use the
    [client credentials flow](/oauth/client_credentials). Register a Service application.
  </Card>
</CardGroup>

## Base URLs

The authorization endpoints are unversioned. The REST API is served under `/api/v1`.

| Purpose                  | URL                                        |
| ------------------------ | ------------------------------------------ |
| Authorize (user consent) | `https://platform.nemu.cc/oauth/authorize` |
| Token                    | `https://platform.nemu.cc/api/oauth/token` |
| REST API base            | `https://platform.nemu.cc/api/v1`          |
| Version discovery        | `https://platform.nemu.cc/api/version`     |

## Register an application

Applications are created in the console. Open Settings, then Applications, then create an
application.

<Steps>
  <Step title="Choose a type">
    Pick Web application for the authorization code flow, or Service for the client credentials
    flow.
  </Step>

  <Step title="Add redirect URIs">
    Web applications must list every redirect URI they will use. We match the `redirect_uri` on
    each request against this list exactly.
  </Step>

  <Step title="Select scopes">
    Grant only the scopes your app needs. See [Scopes](/oauth/scopes).
  </Step>

  <Step title="Copy the credentials">
    You receive a `client_id` and a `client_secret`. The secret is shown once. Store it server
    side and never ship it to a browser.
  </Step>
</Steps>

## Tokens at a glance

<CardGroup cols={2}>
  <Card title="Access token">
    A bearer token sent as `Authorization: Bearer <token>`. It is valid for one hour.
  </Card>

  <Card title="Refresh token">
    Returned by the authorization code flow. It is valid for thirty days and rotates every time
    you use it. The client credentials flow does not use refresh tokens.
  </Card>
</CardGroup>

<Warning>
  The `client_secret`, access tokens, and refresh tokens are confidential. Keep them on your
  server. A user can revoke your app at any time from their account settings.
</Warning>