Skip to main content

Authentication

All Nexla API and Nexla CLI requests require authentication and must be made over HTTPS. Calls made without authentication or over plain HTTP will fail.

Session Access Token​

The first step in calling the Nexla API or Nexla CLI is to fetch an access token by logging on to your Nexla UI instance. This ensures that your authentication is done through your organization's preferred Identity Provider.

To fetch access token from Nexla UI, simply go to your Nexla UI instance and try the route /token. For ex, if your Nexla UI instance is at https://dataops.nexla.io then open https://dataops.nexla.io/token in the browser. It will automatically route you to a login page, ask you to authenticate using your preferred Identity Provider, and upon successful authentication route you to a page where you can copy the Access Token.

Nexla CLI​

You can use the convenience methods nexla env configure or nexla env login on the command line. It will automatically pop-up a browser window for you to authenticate and copy over the token into the terminal.

CLI Access Token Commands: 1
-> nexla env configure
Available Environments:
         - beta.nexla.com *
NEXLA Environment (ex:dataops.nexla.io): dataops.nexla.io
If your browser didn't open, please go to the following link:

        https://dataops.nexla.io/token

Enter ACCESS TOKEN:

CLI Access Token Commands: 2
-> nexla env login
Current Environment: dataops.nexla.io
If your browser didn't open, please go to the following link:

        https://dataops.nexla.io/token

Enter ACCESS TOKEN:

Nexla API​

After fetching the access token from Nexla UI, pass it in subsequent calls to the API as a Bearer token in the Authorization header. For example:

curl https://api.nexla.io/teams                      \
  -H "Authorization: Bearer <Users-Access-Token>"    \
  -H "Accept: application/vnd.nexla.api.v1+json"

Session Token Expiration​

API access tokens expire after an interval specified for the environment. This time is typically one hour. Requests made with expired access tokens will fail with HTTP status 401, Unauthorized. At this point repeat the steps above to re-authenticate and fetch a new Access Token

Session Token Refresh​

If you need to continue a long running automated job sequence using Nexla API or Nexla CLI, you might need to automatically refresh tokens before they expire. You can refresh an access token before it expires by making a POST call to the /token/refresh endpoint.

The new access token is returned in the access_token attribute with the expiration period restarted.

Refresh Session Access Token: Request
curl -X POST <nexla-api-endpoint>/token/refresh      \
  -H "Authorization: Bearer <Users-Access-Token>"    \
  -H "Accept: application/vnd.nexla.api.v1+json"     \
  -H "Content-Length: 0"

Refresh Session Access Token: Response
{
  "access_token": "<Users-New-Access-Token>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "user": {
    "id": 12345,
    "email": "jcw@nexla.com",
    "full_name": "Jeff Williams",
    "api_key": "<Users-API-Key>",
    "super_user": false,
    "impersonated": false,
    "email_verified_at": "2016-02-07T11:40",
    "updated_at": "2016-02-07T11:40",
    "created_at": "2016-02-07T11:40"
  },
  "org": null
}