Keys

What this page is for#

An API key is the credential a client presents to TERSL/DB. The Keys page (/keys) lists the account's keys with their status and when each was last used, and is where an administrator issues new keys, labels them, revokes them and deletes them. A key reaches nothing until a namespace's grants name it, so issuing a key here is usually followed by a visit to Grants.

Who can see it#

Every signed-in user. An administrator sees every key in the account and every action. A limited user sees only the keys they have been given, with the sentence "These are the keys you have been given. Use them in the Explorer.", and no actions; adding, relabelling, revoking and deleting keys are administrator actions.

What is on the page#

The Granted in filter#

When the account has namespaces, a Granted in picker sits at the top. All keys shows every key; choosing a namespace and pressing Filter shows only the keys that namespace's grants name. Clear removes the filter. The list is read from each namespace's grants when the page loads. If the chosen namespace's grants have no # Access section, the page says that nobody is admitted.

The key table#

The table has these columns:

Revoked keys stay in the list, greyed out, so you can see what was turned off and when. Click a header to sort, type in Filter by key id or label to narrow the rows, and open a row's details to edit its label.

The key id is not secret: it is the part of a key that appears in grants documents, in logs and in the portal's URLs. The full key, with its secret, is shown only once, when it is issued; Keys, grants and visibility describes its format.

Actions#

The actions are for administrators.

Add a key#

Press Add key. In the flyout, type a Label of up to 100 characters (the placeholder asks "What will present this key?") and press Add.

The page then shows the key once, under "Copy this key now. It will never be shown again.", with a Copy button. Copy it into the client or secret store that will use it. If it is lost, add another key and revoke this one. The panel ends "Key id 7Q3M9XBK2ADFHNPR. It reaches nothing yet. Grant it in a namespace on Grants."

When the account has as many active keys as the plan allows, the add button is disabled and its caption says "Your plan allows N keys." Revoked keys do not count toward the limit.

Add a portal-only key#

Tick Portal-only in the add flyout. A portal-only key has no secret anyone can hold: the secret is discarded when the key is made, and the page says "Key 7Q3M9XBK2ADFHNPR was issued, and its secret was discarded. There is nothing to copy." The key can be used only through the portal, by the people you give it to on the Users page, for example in the Explorer or on History. The service refuses it if anything presents it directly. This choice cannot be changed later.

A portal-only key is the way to let a person work in a namespace with a specific set of rights without handing them a credential: grant the key what they should be able to do, then give them the key.

Relabel a key#

Open the key's row, change Label for the key id, and press Save. The page says "Renamed 7Q3M9XBK2ADFHNPR." A revoked key can be relabelled. Clients presenting the key are not affected.

Revoke a key#

Press Revoke. The row asks "Revoke this key?" and lists where it is granted, for example "Granted in: 74XEEJ5, 1234567", or "Granted in: nothing." Press Yes, revoke. The page says "Revoked 7Q3M9XBK2ADFHNPR. Anything still presenting it will now be refused."

Within a few seconds the service refuses the key on every request. A revoked key cannot be made active again; issue a new key instead. Its grants are left as they are, so remove its lines from each namespace's grants when you tidy up.

Delete a key#

Press Delete…. A flyout titled "Delete key 7Q3M9XBK2ADFHNPR" says "This permanently removes the key. Every user's access to it is removed and the key can never authenticate again. This action cannot be undone." Type the key id and press Delete key. The key disappears from the list, and every user who was given it loses it. Deleting works on an active key as well as a revoked one.

Explore with a key#

Explore beside an active key opens the Explorer with that key selected.

Related#

• Keys, grants and visibility explains what a key is and how grants bind it to namespaces.
• Grants is where you grant a key in a namespace.
• Users is where you give a key to a person.
• Headers describes how a client presents a key.
• Plans, rates and limits describes the key limit.