API :: Authentication

The access to the Nexaas ID API must be signed by the OAuth access token. The procedure to get the token is described here and here.

The access token can be supplied as bearer authorization HTTP header, that must match the following format:

Authorization: Bearer ee275ec9fb13e98aeb614df2d9691fe91d916

Where ee275ec9fb13e98aeb614df2d9691fe91d916 represents the access token.

Alternatively the system supports query string credencial:

?access_token=ee275ec9fb13e98aeb614df2d9691fe91d916

Prefer bearer authorization.

Getting access token by user authorization

The access can be authorized by the user redirecting the browser to the /oauth/authorize URL, with the following query string (splitted):

client_id=$CLIENT_ID
&
response_type=code
&
redirect_uri=$CALLBACK_URL
&
scope=profile

Or, if your application allows the user to invite other users, require the invite scope too:

client_id=$CLIENT_ID
&
response_type=code
&
redirect_uri=$CALLBACK_URL
&
scope=profile+invite

After authorizing the application, the user will be redirected back to the callback URL, with the query string parameter code.

That code must be send as post data to /oauth/token URL with the content type application/x-www-form-urlencoded or application/json (the example):

{
  "client_id": $CLIENT_ID,
  "client_secret": $CLIENT_SECRET,
  "redirect_uri": $CALLBACK_URL,
  "grant_type": "authorization_code",
  "code": $CODE
}

It will return a JSON bringing the following keys:

{
  "access_token": "the access token",
  "token_type": "bearer",
  "expires_in": "how much seconds to expire",
  "refresh_token": "the refresh token",
  "scope": "profile (maybe invite too)",
  "created_at": "when it was created",
  "api_token": "PW1 API token"
}

PKCE

The PKCE flow for mobile apps is a little different.

Before request authentication, the mobile app must generate:

The code verifier: a random URL-safe 43-character minimum length string;
The code challenge: a SHA-256 hash of the code verifier;
A state: an arbitrary alphanumeric string, suggested state-$UUID.

When the user is redirect to /oauth/authorize, the request must contain the following query string (splitted):

client_id=$CLIENT_ID
&
response_type=code
&
scope=profile
&
redirect_uri=$CALLBACK_URL
&
state=$STATE
&
code_challange=$CODE_CHALLANGE
&
code_challange_method=S256

The provider will redirect the native browser back to the callback URL with the following query string minimal keys (splitted):

code=$AUTHORIZATION_CODE
&
state=$STATE

Then the mobile app must post to the /oauth/token with the content type application/x-www-form-urlencoded or application/json (the example):

{
  "client_id": $CLIENT_ID,
  "client_secret": $CLIENT_SECRET,
  "redirect_uri": $CALLBACK_URL,
  "grant_type": "authorization_code",
  "code": $CODE,
  "code_verifier": $CODE_VERIFIER
}

It will return the same access token response JSON described above.

Client credentials

For getting access token that doesn’t need user authorization, it’s used the client credentials.

The client application needs to access /oauth/token URL directly with the grant type client_credentials:

{
  "client_id": $CLIENT_ID,
  "client_secret": $CLIENT_SECRET,
  "redirect_uri": $CALLBACK_URL,
  "grant_type": "client_credentials"
}

It will return the same access token response JSON described above.

Refresh token

For the access token achievement through refresh token, see the refresh token page.