Authenticate

Send an OIDC bearer token with every API request, verify your identity, and understand the permission model.

Every request to the Akasha API must carry an access token in the Authorization header. Tokens are OIDC access tokens issued by your organization's single sign-on (SSO) — the same identity you use to log in to the console.

Send a bearer token

Add the header to every request:

Authorization: Bearer <access token>

Requests without a token are rejected with 401 (missing Authorization header); expired or malformed tokens are rejected with 401 (invalid token: ...).

Obtain a token

How you obtain an access token depends on how your organization's SSO is configured. Ask your administrator for a client configuration suitable for API access — for example, credentials for a service account or an OAuth client that can issue tokens for the Akasha API.

Your account must have an email address. Tokens for accounts without one are rejected with 403 and error_code: missing_email.

Verify your identity

To check that your token works and see what you can access, call GET /1.0/akasha/rbac/me:

curl -s \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://<your-akasha-endpoint>/1.0/akasha/rbac/me"

{
  "type": "sync",
  "status": "Success",
  "status_code": 200,
  "metadata": {
    "email": "dana@example.com",
    "sub": "…",
    "name": "Dana",
    "groups": ["developers"],
    "permissions": ["akasha:project:dev-team:*"],
    "is_superuser": false,
    "allowed_projects": ["dev-team"]
  }
}

allowed_projects lists every project you can work in; permissions shows the raw grants behind it.

Permission model

Permissions are assigned by your administrator in your organization's SSO and carried in the token. There are two kinds of grants:

Grant	Effect
`akasha:project:<slug>:*`	Full access to everything in the project `<slug>` — instances, networks, storage, clusters
`akasha:superuser`	Platform administrator: access to all projects plus admin-only endpoints

There is no finer-grained permission than per-project access: a project grant gives full control over all resources in that project. To get access to another project, ask your administrator — see Access control.

Authorization errors

Status	Error	Cause
`401`	`missing Authorization header`	No token sent
`401`	`invalid token: ...`	Token expired, malformed, or issued by the wrong issuer
`403`	`error_code: missing_email`	Your account has no email address — ask your administrator
`403`	`error_code: project_access_denied`	The request names a project you do not have access to

Listing GET /1.0/projects never fails for lack of access — the result is filtered to the projects you are allowed to see.