StepSecurity API (Org Access)

In our platform, different organizations are grouped under a single tenant. This page describes API access for an individual organization. For access that applies to managing all organizations under your tenant, refer to this page

The StepSecurity API page at the organization level is where you manage credentials, federation, and API reference for calling the StepSecurity API against a specific organization. It is available under Settings > StepSecurity API in the left navigation, with three tabs:

• API keys, for managing administrative and fine-grained API keys

• OIDC (OpenID Connect) federation, for letting GitHub Actions workflows mint short-lived API tokens without a stored secret

• API reference, an interactive browser for the StepSecurity API endpoints

API keys

Three kinds of API credentials are available at the organization level:

• Organization API Key, a single administrative key for organization-level operations

• Tenant API Key, a single administrative key that also works for tenant-level operations

• Organization fine-grained API keys, scoped service credentials bound to this organization

Organization and Tenant API keys are administrative and broad. Fine-grained keys are the recommended option for service-to-service automation, because you can scope them to only the permissions and lifetime each integration needs.

Organization API Key

The Organization API Key is an administrative API key for organization-level operations. All organization-level APIs work with this key.

You can hold a Primary and a Secondary key at the same time and rotate between them. Use the Rotate button to mint a new value for the selected key. The Last rotated timestamp under each key shows when it was last regenerated.

This key is broad. Prefer a fine-grained API key for anything other than administrative use.

Tenant API Key

The Tenant API Key is an administrative API key for tenant- and organization-level operations. All tenant-level and organization-level APIs work with this key, so it is broader than the Organization API Key.

The Tenant API Key is managed at the tenant level. For details on creating, rotating, and revoking it, see the tenant StepSecurity API page. It is surfaced here for reference and quick rotation.

Organization fine-grained API keys

Notifications will be sent when your fine-grained API keys are about to expire

Fine-grained API keys are long-lived service credentials bound to this organization. They are the recommended way to authenticate backend automation, CI integrations, and any other service that calls the StepSecurity API on behalf of this organization.

Each key has the following properties:

• Scoped to a single organization. The key only authenticates on /v1/github/<organization>/* routes and cannot be used against any other organization

• Fine-grained permissions, scoped to exactly what the integration needs

• Configurable expiration, up to 1 year

• Shown only once at creation

Creating a fine-grained API key

• On the API keys tab, in the Organization fine-grained API keys section, click New key. If you have not created any keys yet, click Create your first key

• Enter a Name. The name is required, helps you identify the key later, and cannot be changed after creation

• Choose an Expiration: 7 days, 30 days, 90 days, or 1 year. You can also enter a Custom (days) value. The Expires at timestamp updates to reflect your choice

• Select Permissions. Use Read all or Read & write all as shortcuts, or expand each category to pick specific permissions. Permission categories include Harden Runner, GitHub Checks, Orchestrate Security, Workflow Run Policies, and others depending on what your tenant has enabled

• Click Create key

• Copy the raw key from the confirmation screen and store it somewhere safe

The raw key is shown only once, immediately after creation. If you close the screen without copying it, you will need to create a new key.

You can only grant permissions you already have. Keys cannot escalate beyond your effective access.

Rotating and revoking

Keys cannot be extended. To rotate, revoke the existing key and create a new one with the duration and permissions you need. Revocation takes effect immediately, and any service still using the old key will start receiving authentication errors on the next request.

To revoke a key, find it in the Organization fine-grained API keys list and remove it.

OIDC federation

OIDC federation lets GitHub Actions workflows under your organization mint short-lived StepSecurity API tokens by exchanging their GitHub OIDC token, without storing a long-lived API key as a secret.

A trust policy is the rule that decides which workflow runs are allowed to exchange their OIDC token, and what permissions the minted StepSecurity token gets. You add one or more policies on the OIDC federation tab.

How GitHub Actions uses the federation

Workflows must request a specific audience when minting their OIDC token, or the exchange will fail with audience-mismatch. The required audience is shown on the OIDC federation tab and follows this pattern:

<organization>.api.stepsecurity.io

For example, an organization named acme-corp would use acme-corp.api.stepsecurity.io.

The OIDC federation tab includes a Show ready-to-paste workflow snippet expandable that contains a complete GitHub Actions example. Copy this into your workflow as a starting point.

Creating an OIDC trust policy

• On the OIDC federation tab, click New policy. If you have not created any policies yet, click Create your first policy

• Enter a Name. The name must be unique within this scope

• (Optional) Add a Description to explain what the policy is for

• Fill in the Required claims. Every non-empty field must equal the corresponding JWT (JSON Web Token) claim from the GitHub OIDC token. Empty fields are wildcards. At least one of Repo owner or Repository is required:

  • Repo owner (repository_owner). Locked to the current organization for org-scope policies

  • Repository (repository), for example acme-corp/infra

  • Workflow ref (job_workflow_ref), for example acme-corp/infra/.github/workflows/deploy.yml@refs/heads/main

  • Ref, for example refs/heads/main

  • Environment, for example production

• Set Max session duration. This caps the lifetime of tokens minted through this policy. The maximum allowed is 1 hour (3600 seconds). Set to 0 to use the server default

• Select Permissions. This is an allowlist applied to tokens minted through this policy and must be a subset of your effective permissions. Use Read all as a shortcut, or expand each category to pick specific permissions

• Click Create policy

Designing claim rules

Keep policies as narrow as the workload you are authorizing. A few patterns:

• For a deploy workflow that should only run from main on a specific repo, fill in Repository, Workflow ref, and Ref. Leave Environment empty unless you want to require it

• For a policy that covers multiple repos under the same owner, fill in Repo owner and leave Repository empty

• Prefer Workflow ref over Ref when you want to pin to a specific workflow file, because Workflow ref includes the file path

Empty fields act as wildcards, so an empty policy with only Repo owner set would match every workflow in the org. Add at least one more claim in production.

API reference

The API reference tab is an interactive browser for the StepSecurity API, rendered from the OpenAPI specification.

You can:

• Browse endpoints grouped by feature area (Overview, Harden Runner, and others)

• Download the raw OpenAPI specification using the Download OpenAPI Spec button, for use in code generators, Postman, or other tooling

• Try requests directly from the browser by clicking Authorize and pasting a valid token

The production server is https://agent.api.stepsecurity.io/v1.

Authorizing in-browser requests

Click Authorize, paste a token, and you can call endpoints directly from the reference. Any of the following token types will work, as long as they have the permissions the endpoint requires:

• A short-lived per-user token from the personal access tokens page

• A fine-grained API key from the API keys tab

• An Organization or Tenant API key

For exploratory or interactive use, a short-lived token is recommended.

Choosing the right credential

Use this rule of thumb:

• Short-lived token, for interactive work from your own machine: MCP (Model Context Protocol) clients, scripts, CLIs, debugging. Max 12 hours, tied to your user

• OIDC federation, for GitHub Actions workflows that need to call the StepSecurity API. No stored secret, tokens are minted on demand

• Fine-grained API key, for service-to-service automation outside GitHub Actions that needs to outlive 12 hours. Up to 1 year, scoped to one organization

• Organization or Tenant API Key, only for administrative operations that need broad access. Rotate them on a schedule

Security best practices

• Prefer OIDC federation over any stored API key when calling from GitHub Actions

• Prefer fine-grained keys over the Organization or Tenant API Key for everything else

• Pick the shortest expiration that fits the integration

• Grant only the permissions the integration actually needs. Avoid Read & write all unless required

• Store raw keys in a secure credential store (secret manager, CI secret). Do not commit them to source control

• Rotate keys before they expire to avoid downtime. Treat any key that may have been exposed as compromised and revoke it immediately

• Keep OIDC trust policies narrow. Pin Repository, Workflow ref, and Ref whenever possible