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.

Hosted Login (Recommended for Web Apps)

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

1. Redirect users to /login on your domain
2. Users authenticate with their preferred provider
3. Cookies are set automatically
4. 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 /_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 /_token endpoint.

---

Identity Providers

RestAPI.com integrates with popular identity providers:

Provider	Description
Microsoft	Personal and work accounts (supports single-tenant for organizations)
Google	Google accounts
Apple	Apple ID
Facebook	Facebook accounts
OpenID Connect	Any OIDC-compliant provider (Auth0, Okta, Keycloak, etc.)
Passkey	WebAuthn passwordless authentication
Vipps	Norwegian mobile payment and login service

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

---

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

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

Configuration

Enable auto-create on a per-provider basis:

1. Go to Security → Auth Providers in the Developer Portal
2. Edit the identity provider you want to configure
3. Enable the Auto-create users option

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)

The user is assigned default roles as configured in your API's security settings.

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

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

Authorization: Bearer <your-token>

Authentication Endpoint

Tokens are obtained from the authentication endpoint:

https://<region>.restapi.com/<api-name>/_auth
https://<api-name>.restapi.cloud/api/_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 /_auth endpoint with your service account credentials:

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

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

OAuth 2.0 Token Endpoint

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

https://<region>.restapi.com/<api-name>/_token
https://<api-name>.restapi.cloud/api/_token

Client Credentials Grant

const response = await fetch('https://eu.restapi.com/my-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('https://eu.restapi.com/my-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('https://eu.restapi.com/my-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('https://eu.restapi.com/my-api/products', {
  headers: {
    'Authorization': `Bearer ${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