Squidex
  • Welcome to Squidex
  • Getting Started
    • Squidex Cloud
    • Installation Instructions
      • Platforms
        • Install on Kubernetes
        • Install on AWS (Deprecated)
        • Install on AWS EC2 using Docker
        • Install on Azure
        • Install on Azure using ARM
        • Install on Google Cloud Platform (GCP)
        • Install on Docker
        • Install on Heroku
        • Install on IIS
        • Install on Render
        • Install on Vultr
      • Configuration
        • Deploying the Image Resizer Service
      • Troubleshooting and Support
        • Diagnose Runtime Issues
        • Restoring Deleted Apps
      • Install Identity (Deprecated)
      • External Identity Providers
        • Azure AD (OAuth) with Squidex
    • Contributing and Developing
      • Building
      • Developing
      • Extensions
        • Custom Rule Action
      • Contributing
      • Architecture
      • Translating
      • Squidex Docs Program
    • Roadmap
    • Quick Start Guides
      • Vue.js Blog with Squidex
      • React.js Blog with Squidex
      • Angular Blog with Squidex
  • Documentation
    • Introduction and Use Case
    • Concepts
      • Apps
      • Teams
      • Schemas
        • Field Rules
      • Content
        • Scheduled Publishing
      • Assets
        • Querying Assets
      • Localization
      • Migrations
      • Roles & Permissions
      • Rules
        • Publish an Event to Azure Queues using Rules
        • Populate Elasticsearch Index
      • Backups
      • Subscriptions
        • App Subscriptions v/s Team Subscriptions
      • Notifications
      • Dashboard
      • Workflows
    • Software Development Kits
      • TypeScript
      • .NET
        • Version v14 (and Earlier)
        • Version v15 (and Later)
      • PHP
      • Java
    • Developer Guides
      • API
        • Authentication
        • Postman
        • Queries
        • Assets
      • Automation Tools (CLI)
      • Scripting
        • Scripting Helper Methods
      • Embed Content
      • Custom Workflows
      • Custom Editors
      • Custom Sidebars
      • Preview Content
      • Rule Formatting
        • Simple
        • Script
        • Liquid
      • Tutorials
        • Building a Blog with Squidex and Next.js
  • Next
    • Squidex 3.0: API Compatibility
Powered by GitBook
On this page
  • Introduction
  • Basic Authentication Flow
  • 1. Generate Clients
  • 2. Request a Token
  • Get access token
  • 3. Use the Token
  • How to Deal With the Access Token

Was this helpful?

  1. Documentation
  2. Developer Guides
  3. API

Authentication

How to Retrieve Access Tokens to Gain Access to the API

PreviousAPINextPostman

Last updated 2 years ago

Was this helpful?

This documentation is based on the FoodCrunch use case. Please open the link below alongside this page to understand the examples.

Introduction

Squidex uses OpenID Connect and OAuth2.0 as authentication protocols. Both are state-of-the-art specifications and adopted by a lot of internet services. You have already used these protocols before, when logging in with your Google account to a third-party website.

The implementation uses , a certified access control solution.

Basic Authentication Flow

First, let's talk about the general authentication flow.

1. Generate Clients

Before you gain an access token you must create a client first. A client is just another name for an application and could be a mobile App, a public website, single page application or a backend server.

If you create a new App, it will already have a default client.

Each client also has a role assigned to define which updates or queries can be performed with the client. This is particularly useful when your client is a public application that can easily be a reversed engineer, like a mobile App or single page application. You can store your client credentials (Client ID and Client Secret) in the application but you have to ensure that you only give your client the necessary permissions and not more.

Read more about permissions in the following link.

2. Request a Token

The client ID and secret cannot be used directly in the API calls. You have to create an additional request to the identity-server first to gain an access token. This token is then valid for 30 days.

Get access token

POST https://cloud.squidex.io/identity-server/connect/token

Get an access token from Squidex Identity.

Request Body

Name
Type
Description

scope

string

squidex-api

client_secret

string

<YOUR_CLIENT_SECRET>

client_id

string

<YOUR_CLIENT_ID>

grant_type

string

client_credentials

{
    "access_token":"<YOUR_ACCESS_TOKEN>,
    "expires_in":2592000,  // Expiration in seconds, 30 days
    "token_type":"Bearer",
    "scope":"squidex-api"
}

Or simply create a request with curl:

curl
    -X POST 'https://cloud.squidex.io/identity-server/connect/token'
    -H 'Content-Type: application/x-www-form-urlencoded'
    -d 'grant_type=client_credentials&
        client_id=<YOUR_CLIENT_ID>&
        client_secret=<YOUR_CLIENT_SECRET>&
        scope=squidex-api

3. Use the Token

Add the returned token to all consecutive requests:

Authorization: Bearer <YOUR_ACCESS_TOKEN>

How to Deal With the Access Token

A frequently asked question is how to deal with the access token, because there are a few challenges:

  1. The token is only valid for 30 days.

  2. The token might expire sooner, for example, when a certificate is replaced on the server.

  3. You need an additional request to get the token.

Our recommendation is to use the following pattern (pseudo code):

function makeRequest(url, body) {
    const token = getTokenFromCache();
    
    if (!token) {
        token = getToken(clientId, clientSecret);
        
        storeTokenInCache(token, days: 30);
    }
    
    const response = makeRequestToSquidex(url, body);
    
    // Token has probably expired. 
    if (response.status == 401) {
        // Request the token again.
        token = getToken(clientId, clientSecret);
        
        storeTokenInCache(token, days: 30);
        
        // Try the request again.
        response = makeRequestToSquidex(url, body);
    }
    
    // You can still have a 401 here, but this very likely not an epxired token then.
    return response;
}

As you can see, we use a simple memory cache to keep our token. We request a new token when it has expired in the cache or on the server and before the first request (after our application started).

You can also request multiple tokens in parallel, for example, when you have a cluster of servers. There is no need to sync the access tokens between your servers or to keep them in a centralized cache.

Roles & Permissions
Introduction and Use Case
IdentityServer4
Default Client