Tokens

Whether you’re running eai CLI commands, a scheduled task on a different machine, or an app that facilitates user interactions with Toolkit, Toolkit needs to know who it’s talking to, and so your requests need to have an auth token attached to them. This is done automatically if you’re running the eai CLI and you’ve done eai login, but for any other case, you’ll need to explicitly pass a token.

But how to actually get your token is the part that’s slightly more complicated. Toolkit offers several ways to obtain auth tokens, but you shouldn’t get them mixed up. Depending on your use case, there will normally be one right tool for the job, and choosing the wrong one might lead to security issues.

Personal User Tokens

Local commands and scripts with the CLI or cURL

If you’re logged into your eai CLI, as mentioned earlier, you won’t need to explicitly pass a token. But if the CLI seems limited for some reason and you need to talk directly to the REST API using cURL or similar, you’ll need to pass an Authorization header with your request. To print out your personal auth token, you can run:

eai login token

Note

This token will expire in the following hour. Running the command every time you need a token ensures that you always get a valid one.

A -H/--header flag is also supported to prefix the token with Authorization: Bearer, as expected by cURL’s -H/--header flag. For example:

curl -H "$(eai login token -H)" https://console.elementai.com/v1/job

Warning

Never share this token with anyone, since it would allow that person to fake your identity and freely interact with Toolkit on your behalf. It should be reserved for circumstances where you’re running a script on your own machine or on a secure remote server that you know no one else will ever be able to access. Even then, be careful! A role might be the better choice.

Via Toolkit Job with Scopes

If you’re serving an app accessible to many users that uses Toolkit data, you’ll likely want to avoid serving information that would be inaccessible to a user otherwise. And on the other hand, you may want your app to display to the user information that the user can access, but that the app developer cannot.

To address this use case, Toolkit jobs can make requests on behalf of a user when responding to a request made to a service route. Note that this must happen from the backend server for the app, as toolkit apps aren’t authorized to make Toolkit API requests directly from the browser.

Here is an example of how to configure an NGINX proxy in a Toolkit job to proxy all calls under /v1/ to the Toolkit API, with proper authorization:

• nginx-default.conf.template

• nginx_start.sh

When a request is made to the backend server, the request first gets handled by the Toolkit API, which takes the user’s session cookie and transforms it into an Authorization header containing the user’s auth token, which then gets passed along with the request to the backend server. From there, your app can simply forward the Authorization header to any requests made to the Toolkit API.

Note

Your job will not be able to freely impersonate the user once receiving their token. Instead, your job must specify a set of “scopes” which are permission policies a user must consent to when first accessing your app. Once the user has consented, your app’s permissions will be equivalent to the intersection of those permissions listed in the job’s scopes, and the permissions of the user sending the request.

Role Tokens

Creating

Long-Lived Tokens

If you’re scheduling a task to run on another machine outside of the Toolkit context (continuous integration runners like CircleCI, Jenkins or Drone are good examples) and you want to make requests to Toolkit as part of those tasks, you’ll want to create a role.

By creating a role and a token instead of passing your own personal token, you reduce the scope of your code’s permissions to a subset of your own permissions. This limits the possible ways a bug in your code could cause something to go wrong as well as the attack surface provided by that token if someone manages to steal it.

1. You first need a role, let’s call it token. Run eai role new org.account.token where org.account is your organization and your account.

2. You can now make a token that will live indefinitely.

EAI_TOKEN=$(eai role key new org.account.token --format text --format-template "{{.Access}}:{{.Secret}}")
echo $EAI_TOKEN

Warning

The eai CLI is automatically using EAI_TOKEN if you have set it with export EAI_TOKEN=.... Call unset EAI_TOKEN to remove the environment variable.

Make sure that when you save and use your role token, you’re not printing out its value in your logs. Many tools offer a “secrets” feature to allow you to keep the value obscured.

Note

You are responsible for the tokens you create. You shouldn’t share them with others. If multiple people need a token for the same role, each one should generate it’s own.

Short-Lived Tokens

If you launch a Toolkit job and want that job to be able to make its own CLI commands or REST API requests to Toolkit, you’ll need to authenticate those requests with a token. But rather than pre-generating a token, you’ll assign the role by ID when you launch the job. From inside the job you can request a short-lived token from toolkit to pass with your requests.

Short-lived tokens are valid for 1 hour. They are extracted out of running jobs. These jobs need to have been submitted with the proper role.

1. You first need a role. Let’s call it myrole. eai role new org.account.myrole where org.account is your

   organization and you account.

2. Submit a job with that role by using --role org.account.myrole, which results

   into eai job new --role org.account.myrole.

3. From inside the job, can call https://internal.console.elementai.com/v1/token to obtain a valid token for 1 hour.

However, this is only the right choice for certain types of jobs. If your job is serving an application that other users can access, consider using Personal User Tokens Via Toolkit Job with Scopes.

Adding Permissions to a Token Through its Associated Role

Hint

Refer to the Permissions page for elaborate information on that topic.

Here is an example to add the permission to read the data org.account.workspace:

eai role policy new org.account.token "data:get@$(eai data get org.account.workspace --field urn)"

Usage Examples

curl

Calling the Toolkit REST API, using the Authorization header:

curl -H "Authorization: Bearer $EAI_TOKEN" https://internal.console.elementai.com/v1/me

Docker

Logging in with the token can be useful when one wants to push an image to a registry during a CD pipeline.

docker login -u console -p "$EAI_TOKEN" https://registry.console.elementai.com

If you want to push to the volatile registry, simply change the last argument to https://volatile-registry.console.elementai.com.

eai

The eai CLI is automatically using the EAI_TOKEN if it is defined.

You can define it for each call:

EAI_TOKEN=$MY_TOKEN eai job ls

Or you can export it:

export EAI_TOKEN=$MY_TOKEN
eai data get ...
eai job get ...
unset EAI_TOKEN