Create and Use API Keys

This guide applies to multi-user Tiled deployments, i.e. deployments configured with an authentication provider.

Note

Single-user deployments run with a single API key. By default, it is randomly generated and printed to the console at server startup, like so:

$ tiled serve pyobject tiled.examples.generated:tree
Generating large example data...
Done generating example data.

    Use the following URL to connect to Tiled:

    "http://127.0.0.1:8000/api?api_key=8df0146c93e9add287d0e7f84a165ba4bd3517bbb3c7c6b4d963c3e1549d0311"

This guide does not apply to single-user deployments like this.

Why use API keys?

Users can log in to Tiled with a simple username/password or through a third party like ORICD or Google, as demonstrated in the tutorial Log into an Authenticated Tiled Server. For interactive workflows in Python, this the most convenient way to authenticate.

But in other situations, it can more convenient to generate and use an API key. An API key uses a comparatively simpler interaction, without an interactive prompt or the need to periodically “refresh” a session to keep it active. This is useful when:

  • The code using tiled is running in an unsupervised, automated fashion or scaled across many workers, such as in an HPC job, where is it not possible to provide credentials interactively.

  • You are connecting from a generic web client like a web browser or curl, which has no built-in integration with Tiled or with OpenAPI+OAuth2.

Create an API Key

To follow along, you may start a Tiled server with a simple authentication provider, as shown. Alternatively, you may use an existing authenticated Tiled server, such as https://tiled-demo.blueskyproject.io/api; if you do, replace http://localhost:8000/api in the examples below with that address.

# You can find example_configs/ in the root of the tiled source code repository.
ALICE_PASSWORD=secret1 tiled serve config example_configs/toy_authentication.yml

Using the Tiled commandline interface, log in as alice using the password secret1.

$ tiled login http://localhost:8000/api
Username: alice
Password:

Create a new API key.

$ tiled api_key create http://localhost:8000/api
48e8f8598940fa0f3e80b406def606e17e815a2c76fe21350a99d6d9935371d11533b318

This text is the API key. It should be handled as a secret.

Note

When typing out http://localhost:8000/api into each command grows tedious, follow Use Profiles to streamline Python client setup to make a convenient alias. The command accepts URL or a profile name.

Use the API Key in Python

We can use it in the Python client:

>>> from tiled.client import from_url
>>> API_KEY = "YOUR_KEY_HERE"
>>> c = from_uri("http://localhost:8000/api", api_key=API_KEY)

API keys should never be placed directly in scripts or notebooks. Instead, set the environment variable TILED_API_KEY.

export TILED_API_KEY=YOUR_KEY_HERE

and then start Python (or IPython, or Jupyter, or…). The Python client will use that, unless it is explicitly passed different credentials.

>>> from tiled.client import from_url
>>> c = from_uri("http://localhost:8000/api")  # uses TILED_API_KEY, if set

Use the API Key in other web clients

We can use in other web clients as well. For example, using HTTPie we can see that unauthenticated requests are refused

$ http http://localhost:8000/api/node/metadata/
HTTP/1.1 401 Unauthorized
content-length: 30
content-type: application/json
date: Mon, 31 Jan 2022 17:30:06 GMT
server: uvicorn
server-timing: app;dur=2.6
set-cookie: tiled_csrf=bZLhKsXVE2VirgXQncHsHn4Y0Wwwr66U0T0hqarJyfw; HttpOnly; Path=/; SameSite=lax
x-tiled-root: http://localhost:8000/api

{
    "detail": "Not authenticated"
}

but passing the API key in the Authorization header as Apikey YOUR_KEY_HERE is accepted. (Note the use of ' quotes.)

$ http http://localhost:8000/api/node/metadata/ 'Authorization:Apikey 48e8f8598940fa0f3e80b406def606e17e815a2c76fe21350a99d6d9935371d11533b318'
HTTP/1.1 200 OK
content-length: 320
content-type: application/json
date: Mon, 31 Jan 2022 17:34:48 GMT
etag: c7d94c99b0a3cd6e102a78520db84bef
server: uvicorn
server-timing: tok;dur=0.0, pack;dur=0.0, app;dur=15.2
set-cookie: tiled_csrf=InE4mplUO0goPxf4V07tVuLSLUvDqhgtALTHYoC3T3s; HttpOnly; Path=/; SameSite=lax
<etc.>

The API key can also be passed in the URL like http://localhost:8000/api/node/metadata/?api_key=YOUR_KEY_HERE. Using the Authorization header is preferred (more secure) but in some situations, as in pasting a link into a web browser, the URL is the only option.

Manage API Keys

We can use the tiled commandline interface to examine and revoke API keys as well.

$ tiled api_key
Usage: tiled api_key [OPTIONS] COMMAND [ARGS]...

  Create, list, and revoke API keys.

Options:
  --help  Show this message and exit.

Commands:
  create
  list
  revoke

We can see the key that we made above in the list.

$ tiled api_key list http://localhost:8000/api
First 8   Expires at (UTC)     Latest activity      Note                Scopes
48e8f859  -                    2022-01-31T18:32:33                      inherit

By default, an API key inherits all the same access as the user who is for. If an API key will be used for a specific task, it is good security hygiene to give it only the privileges it needs for that task. It is also recommended to set a limited lifetimes so that if the key is unknowingly leaked it will not continue to work forever. For example, this command creates an API key that will expire in 10 minutes (600 seconds) and can search/list metadata but cannot download array data.

$ tiled api_key create http://localhost:8000/api --expires-in 600 --scopes read:metadata
ba9af604023a829ab22edb786168d6e1b97cef68c54c6d95d7fad5e3e6347fa131263581

See Scopes for the full list of scopes and their capabilities.

$ tiled api_key list http://localhost:8000/api
First 8   Expires at (UTC)     Latest activity      Note                Scopes
48e8f859  -                    2022-01-31T18:32:33                      inherit
ba9af604  2022-01-31T23:03:57  -                                        read:metadata

Finally, the --note option can be used to label an API key as a reminder of where or how it is being used.

$ tiled api_key create http://localhost:8000/api --note="Data validation pipeline" --scopes read:metadata read:data
573928c62e53096321fb874847bcc6a90ea636eebd8acbd7c5e9d18d2859847b3bfb4f19
$ tiled api_key list http://localhost:8000/api
First 8   Expires at (UTC)     Latest activity      Note                      Scopes
48e8f859  -                    2022-01-31T18:32:33                            inherit
ba9af604  2022-01-31T23:03:57  -                                              read:metadata
573928c6  -                    -                    Data validation pipeline  read:metadata read:data

If an API key is no longer need or accidentally leaked, it should be revoked. It can be identified by its first eight characters, as shown in the the output of tiled api_key list.

$ tiled api_key revoke http://localhost:8000/api 573928c6
$ tiled api_key list http://localhost:8000/api
First 8   Expires at (UTC)     Latest activity      Note                      Scopes
48e8f859  -                    2022-01-31T18:32:33                            inherit
ba9af604  2022-01-31T23:03:57  -                                              read:metadata

Passing the full key also works, if you have it handy. There is no need to trim just the first eight.