StepSecurity API (Org Access)
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 and AWS workloads 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
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 organizationFine-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. Expand each category to pick specific permissions, or use the bulk controls on a category header (No access, Grant read, Clear) to set every permission in that category at once. Categories include Harden Runner, GitHub Checks, Orchestrate Security, Workflow Run Policies, Actions, Reports, Settings, and others depending on what your tenant has enabled. Each permission can be set to No access, Read-only, or Read & write
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.
Settings permissions
The Settings category grants access to the pages under Settings in the organization navigation. It contains four permissions:
Notifications
notifications
Org-level notification routing and channel configuration
API Rate Limits
rate-limits
GitHub API rate-limit consumption observability (customer aggregate and per-owner views)
Organization API Keys
api-keys
Organization-level StepSecurity API keys: the telemetry API key and the self-hosted runner VM API key. Read fetches key values, write rotates them
Control Evaluation
controls
Workflow security controls: summaries, exemptions, suppression, and control settings
API Rate Limits is observability data, so it supports No access and Read-only but not Read & write.

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 a workload mint short-lived StepSecurity API tokens by exchanging an identity token it already has, without storing a long-lived API key as a secret. Two providers are supported:
GitHub Actions
Workflows running under your organization
Repository, ref, and environment, via the GitHub OIDC token
AWS
Workloads running in your AWS account, such as EKS, EC2, and Lambda
Its IAM role, via AWS outbound identity federation
Each trust policy uses one provider. Pick the provider first, because it determines which identity fields the policy matches on.
A trust policy is the rule that decides which workloads are allowed to exchange their identity 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:
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.
How AWS workloads use the federation
AWS workloads authenticate using AWS IAM outbound identity federation, where the workload asks AWS STS for a short-lived, signed JSON Web Token that asserts its identity, then exchanges that token for a StepSecurity API token. Nothing is stored on the workload.
Three things must be in place in AWS before a policy will match:
Outbound identity federation is enabled on the AWS account. Enable it in the IAM console under Account settings, or with
aws iam enable-outbound-web-identity-federation. Enabling it returns an issuer URL unique to the account, which looks likehttps://<uuid>.tokens.sts.global.api.aws. This is the value the trust policy needs. If the feature is already enabled, retrieve the issuer URL withaws iam get-outbound-web-identity-federation-info.The workload's IAM role can request a token. The role needs the
sts:GetWebIdentityTokenpermission.The workload requests the right audience. As with GitHub Actions, an audience mismatch fails the exchange.
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
Choose a Provider, either GitHub Actions or AWS. The identity fields below change to match the provider you pick
GitHub Actions provider. 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 policiesRepository (
repository), for exampleacme-corp/infraWorkflow ref (
job_workflow_ref), for exampleacme-corp/infra/.github/workflows/deploy.yml@refs/heads/mainRef, for example
refs/heads/mainEnvironment, for example
production
AWS provider. Fill in Match AWS identity. The token is minted only for a workload whose identity matches every field you fill in. Issuer URL and AWS account ID are both required:
Issuer URL, for example
https://a1b2c3d4-....tokens.sts.global.api.aws. Your AWS account's outbound-federation issuer, found in IAM under Account settings. This is the trust anchor used to verify tokensAWS account ID, for example
123456789012. The 12-digit account the workload runs inRole ARN (optional), for example
arn:aws:iam::123456789012:role/checks-runner. Matched against the workload's IAM role. Leave it blank to allow any role in the account. Session names and role paths are ignored

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.
For AWS policies, the same principle applies to Role ARN. Leaving it blank trusts every role in the account, which is rarely what you want. Name the specific role the workload runs as, and give that role only the sts:GetWebIdentityToken permission it needs to mint a token.
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
Last updated
Was this helpful?