Authentication

AISafe API authentication uses Bearer tokens in the Authorization header.

API keys

API keys are the recommended authentication method for programmatic access. Each key has the prefix sk-ais- followed by a URL-safe random token.

Creating an API key

1. Go to Settings → API Keys in the AISafe dashboard.
2. Click Create API key.
3. Enter a name for the key, optionally set an expiration, and select the scopes it should have.
4. Copy the key at once. AISafe shows it only once at creation time.

Your organization may enforce API-key lifecycle policy. If so, AISafe can require an expiration, cap the maximum lifetime, auto-fill an expiration when a maximum lifetime is configured, warn the key owner and admins before expiry, and revoke keys that have been inactive beyond the configured window.

Using an API key

Pass the key in the Authorization header:

curl https://api.aisafe.io/api/v1/assessments \
  -H "Authorization: Bearer $AISAFE_API_KEY"

import os
import requests

headers = {"Authorization": f"Bearer {os.environ['AISAFE_API_KEY']}"}
response = requests.get("https://api.aisafe.io/api/v1/assessments", headers=headers)

Scopes

Each API key carries an explicit scope list. Scopes follow a category:action pattern (e.g. assessments:create, findings:read, webhooks:read). A key missing the required scope for an endpoint returns 403 with a message naming the missing scope.

Select only the scopes your integration needs when creating a key. This follows the principle of least privilege. You can create multiple keys with different scopes for different integrations.

Scope catalogue

Organization & membership

Scope	Description
org:read	View organization profile, settings, and metadata
org:update	Change organization name, image, and settings
org:delete	Permanent deletion of the organization (owner-only)
org:transfer_ownership	Transfer the owner role to another member (owner-only)
audit:read	View organization audit-log events and action metadata
audit:export	Download organization audit-log events
governance:read	View retention, SLA, and erasure-request settings
governance:manage	Update retention and remediation SLA policies
governance:erase	File, cancel, or retry GDPR erasure requests
profile:read	View your own profile and notification preferences
profile:update	Update your own profile and notification preferences
billing:read	View credit balance, invoices, and usage
billing:manage	Add credits, change plan, update payment methods
members:read	List organization members
members:invite	Create invite links and send email invites
members:remove	Revoke a member's access to the organization
members:change_role	Promote or demote member roles
teams:read	List teams and team memberships
teams:create	Create a new team
teams:update	Edit team metadata
teams:delete	Delete a team
teams:manage_members	Add or remove members from a team

Integrations & source

Scope	Description
integrations:read	View connected GitHub, GitLab, Bitbucket, Slack, and Teams integrations
integrations:manage	Connect or disconnect integrations
integrations:bind_team	Route integrations to a specific team
issue_exports:read	View configured issue export targets and their status
issue_exports:configure	Create, update, or revoke issue export targets (GitHub, Jira, Linear)
notification_targets:read	View configured notification targets and delivery status
notification_targets:configure	Create, update, or revoke notification targets
notification_targets:test	Send test messages to notification targets
source:connect_personal	Connect a personal GitHub account
source:upload_zip	Upload zipped source for an assessment
source:read_artifacts	Read extracted files from uploaded source
source:download_archive	Download the original source archive

Projects

Scope	Description
projects:read	View projects and their attached assessments
projects:create	Create new projects
projects:update	Edit project metadata, archive/unarchive
projects:delete	Permanent deletion of a project
projects:manage_source	Attach or update a project's source repository or archive

Assessments

Scope	Description
assessments:read	View assessments, drafts, traffic, files
assessments:create	Launch new assessments
assessments:update	Edit draft metadata, settings, notes
assessments:cancel	Cancel a running assessment
assessments:emergency_stop	Emergency-stop an assessment
assessments:archive	Soft-archive completed assessments
assessments:delete	Permanent deletion of an assessment and its findings
assessments:manage_access	Add or remove users/teams from an assessment

Findings

Scope	Description
findings:read	View security findings
findings:triage	Confirm, dismiss, or reassign findings
findings:edit_severity	Override a finding's severity rating
findings:accept_risk	Accept a finding as a known risk
findings:suppress	Permanent suppression of a finding
findings:export_issue	Export a finding to an external issue tracker (GitHub, Jira, Linear)
findings:export	Download findings as SARIF, JSON, or CSV

Reports

Scope	Description
reports:read	View generated reports
reports:generate	Build a new report from an assessment
reports:publish	Publish a report to a shareable URL
reports:share	Grant external access to a report
reports:revoke_share	Revoke external access to a report
reports:download	Download a PDF report

API keys

Scope	Description
api_keys:read	List API keys you own
api_keys:create	Mint new API keys
api_keys:revoke	Revoke API keys
api_keys:rotate	Rotate a key (reserved for future use)

Webhooks

Scope	Description
webhooks:read	View webhook subscriptions and delivery logs
webhooks:create	Create webhook subscriptions
webhooks:update	Edit webhook subscriptions, test delivery, rotate secrets
webhooks:delete	Delete webhook subscriptions

Role-based scope bundles

The requested scopes must be a subset of the creator's role bundle when creating an API key:

Role	Scope bundle
Owner	All scopes (implicit wildcard). The only role allowed to mint wildcard keys (category:* or *).
Admin	Everything except org:delete and org:transfer_ownership.
Manager	Read access to org, own profile, members, teams, integrations, issue exports, notification targets, and source artifacts. Full project, assessment, finding, and report scopes (minus assessments:delete, findings:suppress). Can create and revoke API keys. No webhook or billing access.
Member	Read access to org, own profile, members, teams, integrations, issue exports, projects, assessments, findings, reports, and API keys. Plus profile updates, findings:triage, and api_keys:revoke.

Wildcard scopes

Wildcard scopes (*, assessments:*, etc.) are available to owner-created keys only. Keys created by non-owners must list explicit scopes. Wildcards expand to the concrete scope set before the key is stored.

Rotating and revoking keys

• Rotate: create a new key, update your integration to use it, then revoke the old key.
• Revoke: delete the key from Settings → API Keys. Revocation is immediate; any request using the revoked key returns 401.

Session JWT

For browser-based access (the AISafe dashboard), authentication uses session JWTs from the login and OAuth flows. JWTs are carried in an httpOnly cookie and have a default lifetime of 48 hours. Programmatic clients can use JWTs in the Authorization header, but API keys are recommended for automation.

Two-factor authentication (2FA)

If your account has TOTP-based 2FA enabled, password login returns a partial token that you must exchange for a full session via the 2FA login endpoint. API keys bypass 2FA and authenticate with the key alone.

OAuth providers

AISafe supports GitHub and Google OAuth for account login and signup. These flows create session JWTs. For programmatic access, use API keys.

Related

• API conventions: base URLs, pagination, rate limits
• Errors: how auth errors are represented
• API Reference: per-endpoint documentation