mirror of
https://github.com/SrIzan10/next-auth.git
synced 2026-05-01 10:55:20 +00:00
cb56cd44ca
* docs: beta initial commit * docs(oauth): finish initial tutorial * docs(oauth-tutorial): finish guide * docs(docusaurus): just log broken links * docs: re-organising beta * docs(beta): sort documents for sorting * docs: more re-structure * docs: more re-structure (2) * fix: more WIP * fix: more WIP * chore: more updates * chore: wip * chore: wip * fix lock file * docs(getting-started): credentials * chore: remove json-server file * chore: cleanup * remove mongodb from dev app * chore: cleanup * revert * chore: cleanup * chore: more cleanup changes Co-authored-by: Balázs Orbán <info@balazsorban.com>
74 lines
2.9 KiB
Markdown
74 lines
2.9 KiB
Markdown
---
|
|
id: rest-api
|
|
title: REST API
|
|
---
|
|
|
|
NextAuth.js exposes a REST API that is used by the NextAuth.js client.
|
|
|
|
#### `GET` /api/auth/signin
|
|
|
|
Displays the built-in/unbranded sign-in page.
|
|
|
|
#### `POST` /api/auth/signin/:provider
|
|
|
|
Starts a provider-specific sign-in flow.
|
|
|
|
The POST submission requires CSRF token from `/api/auth/csrf`.
|
|
|
|
In case of an OAuth provider, calling this endpoint will initiate the Authorization Request to your Identity Provider.
|
|
Learn more about this in the [OAuth specification](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.1).
|
|
|
|
In case of using the Email provider, calling this endpoint will send a sign-in URL to the user's e-mail address.
|
|
|
|
This endpoint is also used by the [`signIn`](/getting-started/client#signin) method internally.
|
|
|
|
#### `GET`/`POST` /api/auth/callback/:provider
|
|
|
|
Handles returning requests from OAuth services during sign-in.
|
|
|
|
For OAuth 2.0 providers that support the `checks: ["state"]` option, the state parameter is checked against the one that was generated when the sign in flow was started - this uses a hash of the CSRF token which MUST match for both the `POST` and `GET` calls during sign-in.
|
|
|
|
Learn more about this in the [OAuth specification](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2).
|
|
|
|
#### `GET` /api/auth/signout
|
|
|
|
Displays the built-in/unbranded sign out page.
|
|
|
|
#### `POST` /api/auth/signout
|
|
|
|
Handles signing the user out - this is a `POST` submission to prevent malicious links from triggering signing a user out without their consent. The user session will be invalidated/removed from the cookie/database, depending on the flow you chose to [store sessions](/configuration/options#session).
|
|
|
|
The `POST` submission requires CSRF token from `/api/auth/csrf`.
|
|
|
|
This endpoint is also used by the [`signOut`](/getting-started/client#signout) method internally.
|
|
|
|
#### `GET` /api/auth/session
|
|
|
|
Returns client-safe session object - or an empty object if there is no session.
|
|
|
|
The contents of the session object that is returned are configurable with the [`session` callback](/configuration/callbacks#session-callback).
|
|
|
|
#### `GET` /api/auth/csrf
|
|
|
|
Returns object containing CSRF token. In NextAuth.js, CSRF protection is present on all authentication routes. It uses the "double submit cookie method", which uses a signed HttpOnly, host-only cookie.
|
|
|
|
The CSRF token returned by this endpoint must be passed as form variable named `csrfToken` in all `POST` submissions to any API endpoint.
|
|
|
|
#### `GET` /api/auth/providers
|
|
|
|
Returns a list of configured OAuth services and details (e.g. sign in and callback URLs) for each service.
|
|
|
|
It is useful to dynamically generate custom sign up pages and to check what callback URLs are configured for each OAuth provider that is configured.
|
|
|
|
---
|
|
|
|
:::note
|
|
The default base path is `/api/auth` but it is configurable by specifying a custom path in `NEXTAUTH_URL`
|
|
|
|
e.g.
|
|
|
|
`NEXTAUTH_URL=https://example.com/myapp/api/authentication`
|
|
|
|
`/api/auth/signin` -> `/myapp/api/authentication/signin`
|
|
:::
|