Programmatic API Credentials

FlexGalaxy.ai supports two types of programmatic credentials for API access, mirroring the AWS IAM and STS model.

Overview

Type

Realm

Prefix

Lifecycle

Management

Static credentials

acc-* (tenant IAM users)

AKIA

Long-lived, manually rotated

AdminCenter UI or API

STS temporary credentials

idc-* (Identity Center users)

ASIA

15 min – 12 hours, auto-expires

STS API

Both types produce the same credential format (access key ID + secret key) and use the same authentication mechanism for API calls.

1. Static Credentials (acc-* Users)

Static credentials are long-lived access key / secret key pairs for tenant IAM users. They are analogous to AWS IAM access keys.

Creating via AdminCenter UI

  1. Navigate to AdminCenter → Users → select a user

  2. Click the Security Credentials tab

  3. Click Create access key

  4. Optionally enter a description

  5. Copy the secret key immediately — it is shown only once and cannot be retrieved later

  6. Each user can have a maximum of 2 access keys

Creating via API

curl -X POST https://api.flexgalaxy.com/iam/v1/accounts/{accountId}/credentials \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "principal_id": "<keycloak-user-id>",
    "description": "CI/CD pipeline"
  }'

Response (201):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "access_key_id": "AKIA1A2B3C4D5E6F7G8H",
  "secret_key": "wJalrXUtnFEMI_K7MDENG_bPxRfiCYEXAMPLEKEY...",
  "status": "ACTIVE",
  "principal_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "description": "CI/CD pipeline",
  "created_at": "2026-03-17T10:00:00Z",
  "expires_at": null
}

Warning: The secret_key is returned only in this response. It is stored as a SHA-256 hash and cannot be retrieved later. If lost, delete the credential and create a new one.

Managing credentials

Operation

Method

Path

List

GET

/iam/v1/accounts/{accountId}/credentials?principalId={userId}

Get

GET

/iam/v1/accounts/{accountId}/credentials/{credentialId}

Update (activate/deactivate)

PUT

/iam/v1/accounts/{accountId}/credentials/{credentialId}

Delete

DELETE

/iam/v1/accounts/{accountId}/credentials/{credentialId}

Update example (deactivate):

curl -X PUT https://api.flexgalaxy.com/iam/v1/accounts/{accountId}/credentials/{credentialId} \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"status": "INACTIVE"}'

2. STS Temporary Credentials (idc-* Users)

Identity Center users can obtain short-lived credentials by exchanging their JWT for temporary access key / secret key / session token credentials.

Obtaining temporary credentials

curl -X POST https://api.flexgalaxy.com/iam/v1/sts/get-session-token \
  -H "Authorization: Bearer <idc-realm-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "550e8400-e29b-41d4-a716-446655440000",
    "duration_seconds": 3600
  }'

Response (200):

{
  "access_key_id": "ASIA9X8Y7Z6W5V4U3T2S",
  "secret_key": "wJalrXUtnFEMI_K7MDENG_bPxRfiCYTEMPKEY...",
  "session_token": "FwoGZXIvYXdzEBYaDHqa0AP...",
  "expiration": "2026-03-17T11:00:00Z"
}

Parameters

Parameter

Type

Required

Default

Range

account_id

UUID

Yes

—

Target account

duration_seconds

Integer

No

3600 (1 hour)

900 – 43200 (15 min – 12 hours)

Restrictions

  • Only available for users authenticated via idc-* Keycloak realms

  • Requests from acc-* or flexgalaxy realm JWTs are rejected (400)

  • Expired credentials are automatically cleaned up hourly

Managing STS sessions

Unlike AWS STS, FlexGalaxy supports individual session revocation.

List active sessions:

curl https://api.flexgalaxy.com/iam/v1/sts/sessions?accountId={accountId} \
  -H "Authorization: Bearer <idc-realm-jwt>" \
  -H "X-Account-Id: {accountId}"

Response (200):

[
  {
    "id": "uuid",
    "access_key_id": "ASIA7348AA4A62E56A33",
    "status": "ACTIVE",
    "principal_id": "keycloak-user-uuid",
    "principal_type": "federated",
    "description": "STS temporary credential",
    "created_at": "2026-03-17T18:37:37.941Z",
    "last_used_at": "2026-03-17T18:37:39.518Z",
    "expires_at": "2026-03-17T18:52:37.938Z"
  }
]

Returns all active (non-expired) STS credentials for the calling user in the specified account.

Revoke a single session:

curl -X POST https://api.flexgalaxy.com/iam/v1/sts/revoke-session \
  -H "Authorization: Bearer <idc-realm-jwt>" \
  -H "Content-Type: application/json" \
  -H "X-Account-Id: {accountId}" \
  -d '{"access_key_id": "ASIA9X8Y7Z6W5V4U3T2S"}'

Response (200):

{"message": "Session revoked", "access_key_id": "ASIA9X8Y7Z6W5V4U3T2S"}

The specified temporary credential is immediately deleted. Any subsequent API call using it will fail with 401.

Revoke all sessions:

curl -X POST https://api.flexgalaxy.com/iam/v1/sts/revoke-all-sessions \
  -H "Authorization: Bearer <idc-realm-jwt>" \
  -H "Content-Type: application/json" \
  -H "X-Account-Id: {accountId}" \
  -d '{"account_id": "550e8400-e29b-41d4-a716-446655440000"}'

Response (200):

{"message": "All sessions revoked", "revoked_count": 3}

All active temporary credentials for the calling user in the specified account are immediately deleted.

Operation

Method

Path

Auth

List sessions

GET

/iam/v1/sts/sessions?accountId={id}

JWT (idc-*)

Revoke one

POST

/iam/v1/sts/revoke-session

JWT (idc-*)

Revoke all

POST

/iam/v1/sts/revoke-all-sessions

JWT (idc-*)

3. Using Credentials for API Authentication

Both static and temporary credentials use the same authentication scheme.

Authentication header format

Authorization: FGAI Base64(<access_key_id>:<secret_key>)

For temporary credentials (ASIA prefix), also include:

X-Session-Token: <session_token>

Example: Static credential

# Encode credentials
CREDS=$(echo -n "AKIA1A2B3C4D5E6F7G8H:wJalrXUtnFEMI_K7MDENG_bPxRfiCYEXAMPLEKEY" | base64)

# Make API call
curl https://api.flexgalaxy.com/iam/v1/accounts/{accountId}/users \
  -H "Authorization: FGAI ${CREDS}"

Example: Temporary credential

# Encode credentials
CREDS=$(echo -n "ASIA9X8Y7Z6W5V4U3T2S:wJalrXUtnFEMI_K7MDENG_bPxRfiCYTEMPKEY" | base64)

# Make API call with session token
curl https://api.flexgalaxy.com/iam/v1/accounts/{accountId}/users \
  -H "Authorization: FGAI ${CREDS}" \
  -H "X-Session-Token: FwoGZXIvYXdzEBYaDHqa0AP..."

Authentication flow

  1. Client sends request with Authorization: FGAI <encoded> header

  2. The platform decodes and extracts the access key ID and secret key

  3. Credential is looked up by access key ID

  4. Status (ACTIVE), expiry, and secret key hash are verified

  5. For ASIA prefix: session token is also verified

  6. On success: the request is authenticated with the credential's principal and account

Error responses

Status

Reason

401

Invalid credential format

401

Credential not found

401

Credential is inactive

401

Credential has expired

401

Invalid secret key

401

Missing or invalid session token (ASIA only)

4. Access Key Format

Component

Static

Temporary

Prefix

AKIA

ASIA

Random part

16 hex chars (8 bytes)

16 hex chars (8 bytes)

Total length

20 characters

20 characters

Example

AKIA1A2B3C4D5E6F7G8H

ASIA9X8Y7Z6W5V4U3T2S

Secret key: 54 characters, Base64url-encoded (40 random bytes, no padding).

Session token (STS only): 43 characters, Base64url-encoded (32 random bytes).

5. Security Considerations

Storage

  • Secret keys are never stored in plaintext. Only the SHA-256 hash is persisted.

  • Session tokens are similarly hashed before storage.

Verification

  • Secret key comparison uses constant-time MessageDigest.isEqual() to prevent timing attacks.

Limits

  • Maximum 2 static credentials per IAM user per account.

  • No limit on concurrent STS sessions (they auto-expire).

Best practices

  1. Rotate static keys regularly — create a new key, update your applications, then deactivate/delete the old key.

  2. Prefer STS credentials for interactive or short-lived workloads.

  3. Never embed credentials in source code — use environment variables or secret managers.

  4. Deactivate keys before deleting — allows rollback if something breaks.

  5. Monitor last_used_at — inactive keys that haven't been used should be reviewed for deletion.

6. API Reference Summary

Static Credential CRUD

Method

Path

Auth

Description

POST

/iam/v1/accounts/{id}/credentials

JWT

Create access key

GET

/iam/v1/accounts/{id}/credentials

JWT

List credentials

GET

/iam/v1/accounts/{id}/credentials/{credId}

JWT

Get credential

PUT

/iam/v1/accounts/{id}/credentials/{credId}

JWT

Update status/description

DELETE

/iam/v1/accounts/{id}/credentials/{credId}

JWT

Delete credential

STS

Method

Path

Auth

Description

POST

/iam/v1/sts/get-session-token

JWT (idc-* only)

Get temporary credentials

GET

/iam/v1/sts/sessions?accountId={id}

JWT (idc-*)

List active sessions

POST

/iam/v1/sts/revoke-session

JWT (idc-*)

Revoke one session by access key ID

POST

/iam/v1/sts/revoke-all-sessions

JWT (idc-*)

Revoke all sessions for caller in account

API Authentication

Header

Required

Description

Authorization: FGAI <base64>

Yes

Base64-encoded <access_key_id>:<secret_key>

X-Session-Token

ASIA only

Session token from STS response