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.
-> 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:
-> 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.
- Nexla API
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"
- Nexla API
{
"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
}