Authorization Code Grant


The Authorization Code Grant is an OAuth 2.0 flow that regular web apps use in order to access an API, typically as Web applications with backend and frontend. For more detailed information read OAuth2.0 specifcation. This flow is also applied to a browser-based application (SPA) and it doesn't use client-secret, because the source code is available in a browser - it isn't secure. Instead of this user authorizes the application and redirected back to the application with a temporary code in the URL. The application exchanges that code for the access token.

Basic scheme

Configure Client

Fist step is configure Client for Authorization Grant with secret and redirect_uri, as well code grant type:

PUT /Client/webapp
secret: verysecret
first_party: true
- code
redirect_uri: ''
access_token_expiration: 360
token_format: jwt
secret_required: true
refresh_token: true

Client will act on behalf of the user, which mean Access Policies should be configured for User, not for Client.

You can configure Client for JWT tokens, set token expiration and enable refresh token:






use access token in jwt format


int (seconds)

token expiration time from issued at



enable refresh_token



require secret for token

If you want to use Authorizatin Code Grant for Single Page Application you do not need secret attribute to be set!

If your application is major consumer of Aidbox API you can set first_party attribute into true. This means, that same User Session will be shared between Aidbox and client, so if you close client session Aidbox User Session will be closed too.

Get Code

Next step is to redirect user from your application to Aidbox authorize endpoint with client_id and response_type - code:


To keep you client stateless you can send state parameter with arbitrary content, which will be send you back on redirect.

If user is not logged in - she will see login screen.

If client is not first_party or user not yet granted permissions to client, user will see grant page:

If client granted permissions user agent will be redirected to url configured in Client.auth.authorization_code.redirect_uri with authorization code parameter.


Get Access Token

With this code and client secret you can request for Access Token with grant_type: authorization_code.

POST /auth/token
Content-Type: application/json
"client_id": "web-app",
"client_secret": "verysecret",
"code": <code>,
"grant_type": "authorization_code"

When everything is accurate, you will get response with access token, user information and refresh token (if enabled):

status: 200
"token_type": "Bearer",
"expires_in": 3600,
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODEiLCJzdWIiOiJ1c2VyIiwiaWF0IjoxNTU0NDczOTk3LCJqdGkiOiI0ZWUwZDY2MS0wZjEyLTRlZmItOTBiOS1jY2RmMzhlMDhkM2QiLCJhdWQiOiJodHRwOi8vcmVzb3VyY2Uuc2VydmVyLmNvbSIsImV4cCI6MTU1NDQ3NzU5N30.lCdwkqzFWOe4IcXPC1dIB8v7aoZdJ0fBoIKlzCRFBgv4YndSJxGoJOvIPq2rGMQl7KG8uxGU0jkUVlKxOtD8YA",
"refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODEiLCJzdWIiOiJwYXNzd29yZC1jbGllbnQiLCJqdGkiOiI0ZWUwZDY2MS0wZjEyLTRlZmItOTBiOS1jY2RmMzhlMDhkM2QiLCJ0eXAiOiJyZWZyZXNoIn0.XWHYpw0DysrqQqMNhqTPSdNamBM4ZDUAgh_VupSa7rkzdJ3uZXqesoAo_5y1naJZ31S92-DjPKtPEAyD_8PloA",
"userinfo": {
"email": "",
"id": "user",
"resourceType": "User",

Use Access Token

You can use access token in Authorization header for Aidbox API calls:

GET /Patient
Authorization: Bearer ZjQyNGFhY2EtNTY2MS00NjVjLWEzYmEtMjIwYjFkNDI5Yjhi
curl -H 'Authorization: Bearer ZjQyNGFhY2EtNTY2MS00NjVjLWEzYmEtMjIwYjFkNDI5Yjhi' /Patient

Revoke Access Token (Close Session)

Aidbox create Session (resource) for each Access Token, which can be closed with special endpoint DELETE /Session with token in Authorization header:

DELETE /Session
Authorization: Bearer ZjQyNGFhY2EtNTY2MS00NjVjLWEzYmEtMjIwYjFkNDI5Yjhi

Session is just Resource and you can inspect and manipulate with sessions by standard Search & CRUD API for example get all sessions - GET /Session

Auth Sandbox Demo