Authentication

RestAPI.com uses JWT (JSON Web Tokens) for API authentication. Tokens are issued in response to authentication requests and contain user information including name and role memberships.

The easiest way to add authentication to your web application. RestAPI.com provides a complete hosted login page that handles all authentication flows for you.

How It Works

Redirect users to /login on your domain
Users authenticate with their preferred provider
Cookies are set automatically
Users are redirected back to your app, fully authenticated

That's it. No token handling, no localStorage, no Authorization headers to manage.

Setup

When your app is hosted on the same domain (either <api-name>.restapi.cloud or your custom domain), authentication cookies are shared automatically. Your API calls just work:

// No auth headers needed - cookies are sent automatically
const response = await fetch("/api/products");
const products = await response.json();

Handling Session Expiry

Authentication uses two cookies:

Access cookie — Valid for approximately 1 hour
Refresh cookie — Valid for 70 days from creation

When the access cookie expires, POST to /api/_refresh to get a new one:

async function apiCall(url, options = {}) {
  let response = await fetch(url, options);

  if (response.status === 401) {
    // Refresh - the browser sends the refresh cookie, new access cookie is set automatically
    await fetch("/api/_refresh", { method: "POST" });
    response = await fetch(url, options);

    if (response.status === 401) {
      // Refresh token also expired - redirect to login
      window.location.href = "/login";
      return;
    }
  }

  return response;
}

No tokens to manage in your code. The browser handles all cookie storage and sending automatically.

Recommended Approach

Hosted login is the recommended approach for single-page applications (SPAs) and web apps. It eliminates token management complexity and provides a polished, customizable login experience out of the box.

Mobile Apps (PKCE)

The hosted login also supports PKCE for native mobile apps. Use any OAuth/OIDC library with these endpoints:

Endpoint	URL
Authorization	`https://<api-name>.restapi.cloud/login`
Token	`https://<api-name>.restapi.cloud/api/_token`

The login page handles the OAuth flow and redirects back to your app with an authorization code, which you exchange for tokens at the /api/_token endpoint.

Identity Providers

RestAPI.com integrates with popular identity providers:

Provider	`authority` value	Description
Email & Password	`restapi`	Traditional email and password authentication
One-time code	`restapiOtc`	Passwordless email authentication — a code is sent to the user's email
Microsoft (shared)	`microsoft-shared`	Microsoft sign-in with zero setup — uses the shared Softeria app
Google (shared)	`google-shared`	Google sign-in with zero setup — uses the shared Softeria app
Microsoft	`microsoft`	Personal and work accounts (use `microsoft-enterprise` for single-tenant/org-only)
Google	`google`	Google accounts (use `google-enterprise` for a customer-controlled OAuth client)
Apple	`apple`	Apple ID
Facebook	`facebook`	Facebook accounts
OpenID Connect	`openid`	Any OIDC-compliant provider (Auth0, Okta, Keycloak, etc.) — requires a discovery URL
Passkey	`passkey`	WebAuthn passwordless authentication
Vipps	`vipps`	Norwegian mobile payment and login service (`vipps_mt` for the test environment)

Configure providers in the Developer Portal under Security → Auth Providers.

When adding a provider through the API, set the auth provider's authority field to the exact value in the table above (e.g. google-shared, not google). The shared providers (microsoft-shared, google-shared) require no Client ID — leave it empty and Softeria injects the shared client credentials server-side. Passwordless providers (restapi, restapiOtc, passkey) use no external OAuth client either. The caller-owned Microsoft/Google providers (microsoft, google, and their single-tenant variants microsoft-enterprise, google-enterprise) require your own Client ID.

Common Provider Options

Besides its provider-specific credentials, every auth provider has two options:

Auto-create users on first sign-in (autoCreateUserEnabled) — when enabled, a user record is created automatically the first time someone authenticates via this provider. When disabled, only pre-registered or previously created users can sign in through it. See Auto-Create Users.
Default role (defaultRoleId) — optional, shown once auto-create is enabled. A role from your API's role collection that is granted to every user this provider creates. See Default Role.

Shared Providers (Zero Setup)

The Microsoft (shared) and Google (shared) providers let you offer Microsoft and Google sign-in without registering your own OAuth application. They use a shared app owned by Softeria, so there is no client ID, no client secret, and no per-tenant configuration — just add an auth provider with authority set to microsoft-shared or google-shared (leave the Client ID empty) and it works. Do not use the regular microsoft/google authorities for this — those expect your own Client ID.

Users will see the consent screen branded as Softeria (e.g., "Sign in with Microsoft (Softeria)"), rather than your own application name.

When to Use Shared vs. Your Own App

Consideration	Shared provider	Your own OAuth app
Setup	None — enable and go	Register an app with Microsoft or Google
Consent branding	Softeria	Your application name and logo
Domains	Apps hosted on `<api-name>.restapi.cloud`	Any domain, including custom domains

Custom Domains

Shared providers only work when your app is served from its <api-name>.restapi.cloud address. If your app runs on a custom domain, register your own OAuth application and use the regular Microsoft or Google provider instead.

Email & Password

Email & password authentication allows users to sign in with their email address and a password. No additional configuration is required — just enable the provider.

Pre-Registered Users

You can pre-register users by creating their accounts in advance. Pre-registered users will need to reset their password before they can log in for the first time.

Password Reset

Users can reset their password from the hosted login page. The email address must already be registered. A reset link is sent to the specified email and is valid for 1 hour.

Self-Registration

When Auto-create users on login is enabled for the Email & Password provider, new users can sign up directly with their email and password. An account is created automatically on their first login.

One-time code

One-time code is a passwordless authentication method. Instead of setting up a password, users simply enter their email address and receive a one-time code to sign in.

How It Works

User enters their email address on the login page
A one-time code is sent to their email
User enters the code to complete authentication

No passwords to remember, reset, or manage.

Auto-Create Users

When a user authenticates via an identity provider, RestAPI.com can automatically create a user record if one doesn't already exist. This eliminates the need for a separate registration step.

How It Works

User authenticates via an identity provider (Google, Microsoft, etc.)
RestAPI.com checks if a user exists with the external identity
If no user exists and auto-create is enabled, a new user is created automatically
The user's profile is populated from the identity provider's claims (name, email)

Configuration

Enable auto-create on a per-provider basis:

Go to Security → Auth Providers in the Developer Portal
Edit the identity provider you want to configure
Enable the Auto-create users on first sign-in option
Optionally pick a Default role for the users this provider creates

This allows you to auto-create users from some providers (e.g., your corporate Microsoft tenant) while requiring manual registration for others.

User Creation Details

When a user is auto-created, the following information is captured from the identity provider:

Field	Source
Name	Name claim from the identity token
Email	Email claim from the identity token
External User ID	Unique identifier from the provider (e.g., Google user ID)
Authority	The identity provider (e.g., `google`, `microsoft`)

Default Role

A provider with auto-create enabled can grant a default role to the users it creates. Pick the role in the provider's settings — the option appears once Auto-create users on first sign-in is enabled. The role is applied at the moment the user record is created, so it is already present in the user's very first access token.

Things to know:

The role applies only to newly auto-created users. Existing users and pre-registered users completing their first sign-in keep the roles they already have.
A role that is in use as a provider's default cannot be deleted while auto-create is active — change or clear the provider's default role first.
On Business tenants, auth providers are configured on the master API and user/role data is shared across the tenant, so the granted membership applies tenant-wide — including which applications the new user can open when application access gates are in use.

Without a default role, auto-created users start with no role memberships and can only reach what your access rules grant to the built-in _EVERYONE and _AUTHENTICATED_USER roles.

Pre-Registration

You can also pre-register users by creating user records before they authenticate. When a pre-registered user authenticates for the first time, their account is automatically linked to their external identity. This is useful for:

Assigning specific roles to users before they sign in
Inviting users to your application by email
Migrating users from another system

Service Accounts

Auto-create only applies to users authenticating via identity providers. Service accounts are always created explicitly in the Developer Portal.

Manual Token Authentication

For mobile apps, server-to-server communication, or when you need explicit token control, you can use bearer tokens directly.

How It Works

User authenticates via an identity provider or service account
RestAPI.com issues a JWT bearer token
Include the token in the Authorization header for subsequent requests

Authorization: Bearer <your-token>

Authentication Endpoint

Tokens are obtained from the authentication endpoint:

/api/_auth

For external clients: https://<region>.restapi.com/<api-name>/_auth

Service Accounts

For server-to-server communication without user interaction, use service accounts. Service accounts are created at the API level under Team → Service Accounts.

Getting a Token

POST to the /api/_auth endpoint with your service account credentials:

const response = await fetch("/api/_auth", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    authority: "serviceaccount",
    clientId: "your-client-id",
    clientSecret: "your-client-secret",
  }),
});

const { accessToken } = await response.json();

/api/_auth responds with accessToken, refreshToken, csrfToken and a userInfo object describing the authenticated user. Tokens delivered as cookies are omitted from the body — see Hosted Login.

Two endpoints, two shapes

/api/_auth uses camelCase (accessToken), while the OAuth 2.0 endpoint /api/_token uses the standard snake_case names (access_token). Don't mix them up.

OAuth 2.0 Token Endpoint

For standard OAuth 2.0 integration, use the /api/_token endpoint:

/api/_token

For external clients: https://<region>.restapi.com/<api-name>/_token

Client Credentials Grant

const response = await fetch("/api/_token", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    grant_type: "client_credentials",
    client_id: "your-client-id",
    client_secret: "your-client-secret",
  }),
});

const { access_token, refresh_token, expires_in, token_type } =
  await response.json();

You can also use Basic authentication:

const credentials = btoa("your-client-id:your-client-secret");
const response = await fetch("/api/_token", {
  method: "POST",
  headers: {
    Authorization: `Basic ${credentials}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    grant_type: "client_credentials",
  }),
});

Refresh Token Grant

const response = await fetch("/api/_token", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    grant_type: "refresh_token",
    client_id: "your-client-id",
    refresh_token: "your-refresh-token",
  }),
});

const { access_token, refresh_token, expires_in } = await response.json();

Using the Token

Include the token in your API requests:

const data = await fetch("/api/products", {
  headers: {
    Authorization: `Bearer ${access_token}`,
  },
});

Token Lifetimes

Token	Lifetime
Access token	~1 hour
Refresh token	70 days from creation

Use the refresh token to obtain a new access token before it expires. After 70 days, users must re-authenticate.

Token Contents

JWT tokens contain:

User identity (name, email)
Role memberships
Expiration time
API-specific claims

Security Best Practices

Store tokens securely (never in source code)
Use environment variables for service account credentials
Rotate service account secrets regularly
Use HTTPS for all API requests

Hosted Login (Recommended for Web Apps)​

How It Works​

Setup​

Handling Session Expiry​

Mobile Apps (PKCE)​

Identity Providers​

Common Provider Options​

Shared Providers (Zero Setup)​

When to Use Shared vs. Your Own App​

Email & Password​

Pre-Registered Users​

Password Reset​

Self-Registration​

One-time code​

How It Works​

Auto-Create Users​

How It Works​

Configuration​

User Creation Details​

Default Role​

Pre-Registration​

Manual Token Authentication​

How It Works​

Authentication Endpoint​

Service Accounts​

Getting a Token​

OAuth 2.0 Token Endpoint​

Client Credentials Grant​

Refresh Token Grant​

Using the Token​

Token Lifetimes​

Token Contents​

Security Best Practices​

Hosted Login (Recommended for Web Apps)

How It Works

Setup

Handling Session Expiry

Mobile Apps (PKCE)

Identity Providers

Common Provider Options

Shared Providers (Zero Setup)

When to Use Shared vs. Your Own App

Email & Password

Pre-Registered Users

Password Reset

Self-Registration

One-time code

How It Works

Auto-Create Users

How It Works

Configuration

User Creation Details

Default Role

Pre-Registration

Manual Token Authentication

How It Works

Authentication Endpoint

Service Accounts

Getting a Token

OAuth 2.0 Token Endpoint

Client Credentials Grant

Refresh Token Grant

Using the Token

Token Lifetimes

Token Contents

Security Best Practices