types
This module contains public types and interfaces of the core package.
Installationβ
- npm
- Yarn
- pnpm
npm install @auth/core
yarn add @auth/core
pnpm add @auth/core
You can then import this submodule from @auth/core/type
.
Usageβ
Even if you don't use TypeScript, IDEs like VSCode will pick up types to provide you with a better developer experience. While you are typing, you will get suggestions about what certain objects/functions look like, and sometimes links to documentation, examples, and other valuable resources.
Generally, you will not need to import types from this module.
Mostly when using the Auth
function and optionally the AuthConfig
interface,
everything inside there will already be typed.
Inside the Auth
function, you won't need to use a single type from this module.
Exampleβ
import { Auth } from "@auth/core"
const request = new Request("https://example.com")
const response = await Auth(request, {
callbacks: {
jwt(): JWT { // <-- This is unnecessary!
return { foo: "bar" }
},
session(
{ session, token }: { session: Session; token: JWT } // <-- This is unnecessary!
) {
return session
},
}
})
We are advocates of TypeScript, as it will help you catch errors at build-time, before your users do. π
Resourcesβ
AuthActionβ
AuthAction:
"callback"
|"csrf"
|"error"
|"providers"
|"session"
|"signin"
|"signout"
|"verify-request"
Supported actions by Auth.js. Each action map to a REST API endpoint.
Some actions have a GET
and POST
variant, depending on if the action
changes the state of the server.
"callback"
:GET
: Handles the callback from an OAuth provider.POST
: Handles the callback from a Credentials provider.
"csrf"
: Returns the raw CSRF token, which is saved in a cookie (encrypted). It is used for CSRF protection, implementing the double submit cookie technique.
Some frameworks have built-in CSRF protection and can therefore disable this action. In this case, the corresponding endpoint will return a 404 response. Read more at skipCSRFCheck
.
β We don't recommend manually disabling CSRF protection, unless you know what you're doing.
"error"
: Renders the built-in error page."providers"
: Returns a client-safe list of all configured providers."session"
:- **
GET**
: Returns the user's session if it exists, otherwisenull
. - **
POST**
: Updates the user's session and returns the updated session.
- **
"signin"
:GET
: Renders the built-in sign-in page.POST
: Initiates the sign-in flow.
"signout"
:GET
: Renders the built-in sign-out page.POST
: Initiates the sign-out flow. This will invalidate the user's session (deleting the cookie, and if there is a session in the database, it will be deleted as well).
"verify-request"
: Renders the built-in verification request page.
ErrorPageParamβ
ErrorPageParam:
"Configuration"
|"AccessDenied"
|"Verification"
TODO: Check if all these are used/correct
SignInPageErrorParamβ
SignInPageErrorParam:
"Signin"
|"OAuthSignin"
|"OAuthCallbackError"
|"OAuthCreateAccount"
|"EmailCreateAccount"
|"Callback"
|"OAuthAccountNotLinked"
|"EmailSignin"
|"CredentialsSignin"
|"SessionRequired"
TODO: Check if all these are used/correct
TokenSetβ
TokenSet:
Partial
<OAuth2TokenEndpointResponse
|OpenIDTokenEndpointResponse
> &object
Different tokens returned by OAuth Providers. Some of them are available with different casing, but they refer to the same value.
Type declarationβ
expires_atβ
expires_at?:
number
Date of when the access_token
expires in seconds.
This value is calculated from the expires_in
value.
Seeβ
https://www.ietf.org/rfc/rfc6749.html#section-4.2.2
Accountβ
Usually contains information about the provider being used
and also extends TokenSet
, which is different tokens returned by OAuth Providers.
Extendsβ
Partial
<OpenIDTokenEndpointResponse
>
Propertiesβ
providerβ
provider:
string
Provider's id for this account. Eg.: "google"
providerAccountIdβ
providerAccountId:
string
This value depends on the type of the provider being used to create the account.
- oauth/oidc: The OAuth account's id, returned from the
profile()
callback. - email: The user's email address.
- credentials:
id
returned from theauthorize()
callback
typeβ
type:
ProviderType
Provider's type for this account
expires_atβ
expires_at?:
number
Calculated value based on [OAuth2TokenEndpointResponse.expires_in]([object Object]).
It is the absolute timestamp (in seconds) when the [OAuth2TokenEndpointResponse.access_token]([object Object]) expires.
This value can be used for implementing token rotation together with [OAuth2TokenEndpointResponse.refresh_token]([object Object]).
Seeβ
- https://authjs.dev/guides/basics/refresh-token-rotation#database-strategy
- https://www.rfc-editor.org/rfc/rfc6749#section-5.1
userIdβ
userId?:
string
id of the user this account belongs to
Seeβ
https://authjs.dev/reference/core/adapters#user
CallbacksOptions<P, A>β
Override the default session creation flow of Auth.js
Type parametersβ
βͺ P = Profile
βͺ A = Account
Propertiesβ
jwtβ
jwt: (
params
) =>Awaitable
<null
|JWT
>
This callback is called whenever a JSON Web Token is created (i.e. at sign in)
or updated (i.e whenever a session is accessed in the client).
Its content is forwarded to the session
callback,
where you can control what should be returned to the client.
Anything else will be kept from your front-end.
The JWT is encrypted by default.
Documentation |
session
callback
Parametersβ
βͺ params: object
βͺ params.account: null
| A
Contains information about the provider that was used to sign in. Also includes TokenSet
Note
available when trigger
is "signIn"
or "signUp"
βͺ params.token: JWT
When trigger
is "signIn"
or "signUp"
, it will be a subset of JWT,
name
, email
and image
will be included.
Otherwise, it will be the full JWT for subsequent calls.