Organization API Keys

Organization API keys authenticate automation such as CI/CD pipelines. Unlike a personal API key created from your Profile, an organization API key is owned by the organization. It keeps working when the person who created it changes roles or leaves the organization.

Every organization API key starts with nso_. The secret is shown exactly once, when the key is created, and Nullstone stores only a hash of it.

TIP

Use organization API keys for anything that runs unattended. Personal API keys are intended for your own workstation.

Create a key

1. Open your organization settings (bottom left of the sidebar) and choose API Keys.
2. Click Create API Key and give the key a name. Name the key after the system that will hold it, for example github or circleci.
3. Choose an Organization role (see below).
4. Add one or more Stack scopes (see below).
5. Copy the key from the one-time reveal and store it in your CI system's secret store.

Only organization architects and admins can create, edit, or delete organization API keys. A key can never be granted more access than the person creating it holds.

Organization role

The organization role controls what the key can do at the organization level. It mirrors the organization roles for people.

Member

The default. The key can only act within the stacks listed in its stack scopes. Use this for deploy pipelines.

Architect

Everything a member key can do, plus the organization-level abilities of an architect:

• Register modules and publish module versions
• Manage integrations and cost providers
• Update and delete stacks

Use this for pipelines that publish custom modules to the Nullstone registry. Stack scopes are optional for an architect key; add them only if the same key also deploys applications.

Only an organization architect or admin can grant the architect role to a key.

WARNING

An organization API key can never be an Admin. Managing members, invitations, cloud provider credentials, billing, and other API keys always requires a person. An architect key also cannot create new stacks, because stack ownership is assigned to a person.

Stack scopes

Each stack scope grants the key a stack role on one stack: Software Engineer, Architect, or Owner. The key cannot see stacks that are not in its scopes.

You can only scope a key to stacks where you are a member, up to your own role on each stack.

Use the key

Set two environment variables wherever the CLI runs.

NULLSTONE_ORG=<your organization name>
NULLSTONE_API_KEY=<nso_...>

The CLI reads the block, environment, and stack from NULLSTONE_BLOCK, NULLSTONE_ENV, and NULLSTONE_STACK as well, so a pipeline step needs no flags.

nullstone outputs --field=role_arn

WARNING

On a machine where nullstone configure has already stored a key, that stored key takes precedence over NULLSTONE_API_KEY. Run pipelines on clean runners, or point NULLSTONE_PROFILE at a profile that has no stored key.

Some CLI commands act on behalf of a person, such as creating an organization or managing stack members. Those commands reject organization API keys with a descriptive error.

Change or revoke a key

Editing a key's organization role or stack scopes takes effect on the key's next request. There is no need to create a new key or update your CI secrets.

Deleting a key revokes it immediately. To rotate a key, create a new key, update the secret in your CI system, then delete the old key.

The API Keys page shows who created each key and when it was last used.