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 example, if your Nexla UI instance is located at https://dataops.nexla.io, 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.
Access tokens can also be fetched by using a service key to programmatically access Nexla.
To learn how to generate and use a service key for your Nexla account, see the Service Keys section below.
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
}
Service Keys
Service keys are forever keys that can be used to programmatically access Nexla and obtain a session token.
To create a service key for your account from the Nexla UI, navigate to the Authentication screen in the Integrate section, and click the Create Service Key button.
These keys should be treated as highly senstive and should never be exposed to your end-users, as they are equivalent to your account password. Store the key securely, and avoid sending it over the air from your server to the client browser.
Obtain a Session Token
Session tokens can be obtained after authenticating using a service key by passing a POST call to the Nexla API /token endpoint.
curl -X POST <nexla-api-endpoint>/token \
-H "Authorization: Basic <Service-Key>" \
-H "Accept: application/vnd.nexla.api.v1+json" \
-H "Content-Length: 0"