Skip to main content

API keys

An API key lets astroctl, a script or your own code call the AstroPulse API as you, in one organization, without a browser login. Each key belongs to you and to the organization it was created in. For production automation that must keep working when people leave, use a service account key instead: it belongs to the organization, not to a person.

Before you start​

  • A member of the organization. Anyone can create keys for themselves.
  • The organization picked in the switcher at the top of the sidebar: a key works in that organization only.
  • Room under the organization's API key limit: 3 on Developer, 1,000 by default on Enterprise (it can be changed for your organization), shared by personal and service account keys. Expired and revoked keys free their places.

In the console​

  1. Open API Keys in the sidebar and select Create API Key.

  2. Enter a Name that says where the key is used, for example local-dev.

  3. Pick Expires after: 1 hour to 30 days, with 24 hours (default), or Custom duration... in hours, minutes or days (for example 12h, 30m, 7d). Turn on Never expires only for a key you will revoke yourself.

    Open zoom view

    Create API key in the Default Organization, with a name, Expires after 24 hours (default) and Never expires off

    Create API key in the Default Organization, with a name, Expires after 24 hours (default) and Never expires offCreate API key in the Default Organization, with a name, Expires after 24 hours (default) and Never expires off

  4. Select Create key. Key created shows the key once, with a copy button: "Store it now. You won't see it again." Copy it into your secret store, then select Done.

You should see​

The key in the list with its Name, Source (CLI for a key astroctl made, Console for one made in the console, Nova for the one Nova made for you), its masked Key, Created, Last used ("Never used" until its first call), Expires ("Never" for a key that does not expire) and Status. Filter by status, by Permanent or Temporary, and by source.

Open zoom view

API Keys: each key with its source, masked key, dates and status, and the status, type and source filters

API Keys: each key with its source, masked key, dates and status, and the status, type and source filtersAPI Keys: each key with its source, masked key, dates and status, and the status, type and source filters

Use a key​

astroctl uses the key in ASTROPULSE_API_KEY and skips the browser login:

Terminal
export ASTROPULSE_API_KEY=<your-api-key>
astroctl whoami

Your own code sends it in the X-Astro-API-Key header on every request. The API reference lists every call.

Revoke or delete a key​

From the key's row:

  • Revoke key stops the key on its next request. The record stays, marked Revoked with who revoked it, when and the reason you give, so the key stays accounted for. Use it when a key may have leaked.
  • Delete key removes the record entirely.

How keys are kept safe​

  • The full key is shown once, when it is created. The list shows only its name and dates, never the key.
  • A key works in one organization, as you, and stops working when it expires or is revoked.
  • Short expiry is the default: 24 hours in the console. A key that does not expire is a choice you make, and the list marks it Permanent.
  • Revoking keeps the key's record, with who revoked it and why.

Other ways in​

With astroctl​

Terminal
astroctl auth login
astroctl auth login --key-name ci-deploy --api-key-duration 720h
astroctl auth apikey list
astroctl auth apikey revoke <key-id> --reason "laptop lost"

login reuses the key this machine already holds for the organization, and makes one only when it has none that works. A key it makes is named after the machine's hostname; --key-name names it instead, and --new-api-key makes a new one even when a working key is held. revoke takes the key's ID from list, not the key itself. Every flag: astroctl auth apikey.

Settings​

Namename

What the key is for. Shown in the list; the key itself is not.

Expires afterduration

How long the key works.

Accepts
1 hour to 30 days, or a custom duration in hours, minutes or days, such as 12h, 30m or 7d.
Default
24 hours in the console; 720h (30 days) for a key astroctl auth login makes.
Never expirespermanent

The key works until you revoke or delete it.

Default
Off

If it's refused​

Every refused key is answered with HTTP 401 and one of these.

"No API key was sent. Send your API key in the X-Astro-API-Key header."
Cause
The request carried no key.
Fix
Send it in the X-Astro-API-Key header, or set ASTROPULSE_API_KEY for astroctl.
"The API key is not valid. Create a new key in the console under Organization settings › API Keys, or sign in again with the CLI, which creates a new key."
Cause
The key is not one AstroPulse issued, or it was deleted.
Fix
Create a new key.
"The API key has expired. Create a new key in the console under Organization settings › API Keys, or sign in again with the CLI, which creates a new key."
Cause
The key passed its Expires at time.
Fix
Create a new key, with a longer Expires after if the job runs longer.
"The API key has been revoked. Create a new key in the console under Organization settings › API Keys, or sign in again with the CLI, which creates a new key."
Cause
Someone revoked the key. The list shows who and why.
Fix
Create a new key.
"The API key is in a format that is no longer accepted. Create a new key in the console under Organization settings › API Keys, or sign in again with the CLI, which creates a new key."
Cause
The key was made in an older format.
Fix
Create a new key.

Next​