Identity & Access Management

The Identity & Access Management API provides comprehensive role-based access control functionality for managing users, teams, roles, and API keys in Firefly.

Users

List Users

List users

get

List and filter users for the specified account

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

accountIdstringRequired

Account ID

Query parameters

searchstring · max: 255Optional

Search users by name or email using full-text search

Example: [email protected]

emailstring · email · max: 255Optional

Filter by exact email address match (returns single user or empty array)

Example: [email protected]

typestring · enumOptional

Filter by user type - either regular USER or Service Account (SA)

Example: USERPossible values:

role_idsstring · uuid[] · max: 50Optional

Filter by role IDs - users must have at least one of these roles

Example: ["550e8400-e29b-41d4-a716-446655440000"]

team_idsstring · uuid[] · max: 50Optional

Filter by team IDs - users must be members of at least one of these teams

Example: ["660f9511-f3ac-52e5-b827-557766551111"]

limitinteger · min: 1 · max: 100Optional

Maximum number of users to return

Default: 25Example: 25

offsetintegerOptional

Number of users to skip

Default: 0Example: 0

Responses

200

Array of users matching the search criteria

application/json

400

Bad request

application/json

401

Unauthorized

403

Forbidden

get

/user-service/users

HTTPcURLJavaScriptPython

GET /v2/user-service/users HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "users": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "account_id": "text",
      "name": "text",
      "email": "[email protected]",
      "description": "text",
      "profile_photo": "https://example.com",
      "created_at": "2026-01-20T23:21:30.944Z",
      "last_login": "2026-01-20T23:21:30.944Z",
      "email_verified": true,
      "assigned_role_ids": [
        "123e4567-e89b-12d3-a456-426614174000"
      ],
      "team_ids": [
        "123e4567-e89b-12d3-a456-426614174000"
      ],
      "connection": "text",
      "created_by": "123e4567-e89b-12d3-a456-426614174000",
      "created_by_name": "text",
      "system_generated": true,
      "type": "USER"
    }
  ],
  "total_count": 42
}

Create User

Create a user

post

Create a new user in the system

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

accountIdstringRequired

Account ID

Body

application/json

namestringRequired

User's name

typestring · enumRequired

User type - either regular USER or Service Account (SA)

Possible values:

emailstring · emailOptional

User's email address (required for type 'user', optional for type 'SA')

descriptionstring | nullableOptional

User's description or bio (optional, commonly used for SA)

role_idsstring · uuid[]Optional

List of role IDs to assign to the user

team_idsstring · uuid[]Optional

List of team IDs to add the user to

profile_photostring · uri | nullableOptional

URL to user's profile photo

created_bystring · email | nullableOptional

Email address of the person creating this user (will be looked up in the database)

onboarding_userbooleanOptional

If true, automatically assigns the 'Admin' role (from account_id=null) to the user

Default: false

is_ssobooleanOptional

If true, skips Auth0 user creation and password reset email. Use this flag for SSO users managed externally.

Default: false

Responses

201

Created user

application/json

400

Bad request

application/json

401

Unauthorized

403

Forbidden

409

User already exists

post

/user-service/users

HTTPcURLJavaScriptPython

POST /v2/user-service/users HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 286

{
  "name": "text",
  "type": "USER",
  "email": "[email protected]",
  "description": "text",
  "role_ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "team_ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "profile_photo": "https://example.com",
  "created_by": "[email protected]",
  "onboarding_user": false,
  "is_sso": false
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "account_id": "text",
  "name": "text",
  "email": "[email protected]",
  "description": "text",
  "profile_photo": "https://example.com",
  "created_at": "2026-01-20T23:21:30.944Z",
  "last_login": "2026-01-20T23:21:30.944Z",
  "email_verified": true,
  "assigned_role_ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "team_ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "connection": "text",
  "created_by": "123e4567-e89b-12d3-a456-426614174000",
  "created_by_name": "text",
  "system_generated": true,
  "type": "USER"
}

Get User

Get a user

get

Retrieve details of a specific user

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

accountIdstringRequired

Account ID

userIdstring · uuidRequired

User ID

Responses

200

User object

application/json

401

Unauthorized

403

Forbidden

404

User not found

get

/user-service/users/{userId}

HTTPcURLJavaScriptPython

GET /v2/user-service/users/{userId} HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "account_id": "text",
  "name": "text",
  "email": "[email protected]",
  "description": "text",
  "profile_photo": "https://example.com",
  "created_at": "2026-01-20T23:21:30.944Z",
  "last_login": "2026-01-20T23:21:30.944Z",
  "email_verified": true,
  "assigned_role_ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "team_ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "connection": "text",
  "created_by": "123e4567-e89b-12d3-a456-426614174000",
  "created_by_name": "text",
  "system_generated": true,
  "type": "USER"
}

Update User

Delete User

Delete a user

delete

Delete a user from the system

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

accountIdstringRequired

Account ID

userIdstring · uuidRequired

User ID

Responses

204

User deleted successfully

401

Unauthorized

403

Forbidden

404

User not found

delete

/user-service/users/{userId}

HTTPcURLJavaScriptPython

DELETE /v2/user-service/users/{userId} HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Teams

Get Current User's Team

List Teams

List teams

get

Retrieve a list of teams for the specified account

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

accountIdstringRequired

Account ID

Query parameters

limitinteger · min: 1 · max: 100Optional

Maximum number of teams to return

Default: 25

offsetintegerOptional

Number of teams to skip

Default: 0

searchstring · max: 255Optional

Search teams by name (partial match)

role_idsstring · uuid[]Optional

Filter teams by role IDs (comma-separated)

Responses

200

Array of teams

application/json

400

Bad request

application/json

401

Unauthorized

403

Forbidden

get

/user-service/teams

HTTPcURLJavaScriptPython

GET /v2/user-service/teams HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "teams": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "account_id": "text",
      "name": "text",
      "description": "text",
      "users": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "name": "text"
        }
      ],
      "attached_role_ids": [
        "123e4567-e89b-12d3-a456-426614174000"
      ],
      "created_at": "2026-01-20T23:21:30.944Z",
      "updated_at": "2026-01-20T23:21:30.944Z"
    }
  ],
  "total_count": 42
}

Create Team

Get Team

Get a team

get

Retrieve details of a specific team

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

accountIdstringRequired

Account ID

teamIdstring · uuidRequired

Team ID

Responses

200

Team object

application/json

401

Unauthorized

403

Forbidden

404

Team not found

get

/user-service/teams/{teamId}

HTTPcURLJavaScriptPython

GET /v2/user-service/teams/{teamId} HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "account_id": "text",
  "name": "text",
  "description": "text",
  "users": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text"
    }
  ],
  "attached_role_ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "created_at": "2026-01-20T23:21:30.944Z",
  "updated_at": "2026-01-20T23:21:30.944Z"
}

Update Team

Delete Team

Delete a team

delete

Delete a team from the system

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

accountIdstringRequired

Account ID

teamIdstring · uuidRequired

Team ID

Responses

204

Team deleted successfully

401

Unauthorized

403

Forbidden

404

Team not found

delete

/user-service/teams/{teamId}

HTTPcURLJavaScriptPython

DELETE /v2/user-service/teams/{teamId} HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

List Team Members

Update Team Members

Bulk Update Team Members

Add multiple users to team

post

Add multiple users to the specified team in a single operation

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

accountIdstringRequired

Account ID

teamIdstring · uuidRequired

Team ID

Body

application/json

user_idsstring · uuid[] · min: 1 · max: 100Required

Array of user IDs to add to the team

skip_existingbooleanOptional

Skip users that are already in the team instead of returning error

Default: true

Responses

201

Users added to team successfully

application/json

400

Bad request

application/json

401

Unauthorized

403

Forbidden

404

Team not found

post

/user-service/teams/{teamId}/members/bulk

HTTPcURLJavaScriptPython

POST /v2/user-service/teams/{teamId}/members/bulk HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 74

{
  "user_ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "skip_existing": true
}

{
  "message": "Users added to team successfully",
  "added_users": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "skipped_users": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "failed_users": [
    {
      "user_id": "123e4567-e89b-12d3-a456-426614174000",
      "error": "text"
    }
  ]
}

API Keys

List API Keys

List API keys

get

Retrieve a list of API keys for the specified account

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

accountIdstringRequired

Account ID

Query parameters

searchstring · max: 255Optional

Search API keys by alias, description, user name, or team name using full-text search

typestring · enumOptional

Filter by API key type

Possible values:

emailstring · emailOptional

Filter by user email (only returns USER type API keys with matching email)

user_idstring · uuidOptional

Filter by user ID (returns API keys associated with this user)

team_idstring · uuidOptional

Filter by team ID (returns API keys associated with this team)

limitinteger · min: 1 · max: 100Optional

Maximum number of API keys to return

Default: 25

offsetintegerOptional

Number of API keys to skip

Default: 0

Responses

200

Array of API keys

application/json

400

Bad request

application/json

401

Unauthorized

403

Forbidden

get

/user-service/api-keys

HTTPcURLJavaScriptPython

GET /v2/user-service/api-keys HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "api_keys": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "key": "text",
      "is_legacy": false,
      "account_id": "text",
      "type": "TEAM",
      "user_id": "123e4567-e89b-12d3-a456-426614174000",
      "user_name": "text",
      "team_id": "123e4567-e89b-12d3-a456-426614174000",
      "team_name": "text",
      "alias": "text",
      "description": "text",
      "expires_at": "2026-01-20T23:21:30.944Z",
      "last_used": "2026-01-20T23:21:30.944Z",
      "created_by": "123e4567-e89b-12d3-a456-426614174000",
      "created_by_name": "text",
      "created_at": "2026-01-20T23:21:30.944Z",
      "updated_at": "2026-01-20T23:21:30.944Z"
    }
  ],
  "total_count": 42
}

Create API Key

Create an API key

post

Generate a new API key

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

accountIdstringRequired

Account ID

Body

application/json

typestring · enumRequired

Type of API key (scope)

Possible values:

user_idstring · uuid | nullableOptional

User ID (required when type is USER)

team_idstring · uuid | nullableOptional

Team ID (required when type is TEAM)

aliasstring | nullableOptional

Human-readable alias for the API key

descriptionstring | nullableOptional

Description of the API key's purpose

expires_atstring · date-time | nullableOptional

When the API key should expire (must be in the future, RFC3339 format)

created_bystring · email | nullableOptional

Email address of the person creating this API key (will be looked up in the database)

system_generatedboolean | nullableOptional

If true, creates an SA type user with admin role and attaches the API key to it (similar to migration logic)

Default: false

Responses

201

Created API key

application/json

400

Bad request

application/json

401

Unauthorized

403

Forbidden

post

/user-service/api-keys

HTTPcURLJavaScriptPython

POST /v2/user-service/api-keys HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 244

{
  "type": "TEAM",
  "user_id": "123e4567-e89b-12d3-a456-426614174000",
  "team_id": "123e4567-e89b-12d3-a456-426614174000",
  "alias": "text",
  "description": "text",
  "expires_at": "2026-01-20T23:21:30.944Z",
  "created_by": "[email protected]",
  "system_generated": false
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "key": "text",
  "is_legacy": false,
  "account_id": "text",
  "type": "TEAM",
  "user_id": "123e4567-e89b-12d3-a456-426614174000",
  "user_name": "text",
  "team_id": "123e4567-e89b-12d3-a456-426614174000",
  "team_name": "text",
  "alias": "text",
  "description": "text",
  "expires_at": "2026-01-20T23:21:30.944Z",
  "last_used": "2026-01-20T23:21:30.944Z",
  "created_by": "123e4567-e89b-12d3-a456-426614174000",
  "created_by_name": "text",
  "created_at": "2026-01-20T23:21:30.944Z",
  "updated_at": "2026-01-20T23:21:30.944Z",
  "secret": "text"
}

Get API Key

Get an API key

get

Retrieve details of a specific API key

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

accountIdstringRequired

Account ID

keyIdstring · uuidRequired

API Key ID

Responses

200

API Key object

application/json

401

Unauthorized

403

Forbidden

404

API key not found

get

/user-service/api-keys/{keyId}

HTTPcURLJavaScriptPython

GET /v2/user-service/api-keys/{keyId} HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "key": "text",
  "is_legacy": false,
  "account_id": "text",
  "type": "TEAM",
  "user_id": "123e4567-e89b-12d3-a456-426614174000",
  "user_name": "text",
  "team_id": "123e4567-e89b-12d3-a456-426614174000",
  "team_name": "text",
  "alias": "text",
  "description": "text",
  "expires_at": "2026-01-20T23:21:30.944Z",
  "last_used": "2026-01-20T23:21:30.944Z",
  "created_by": "123e4567-e89b-12d3-a456-426614174000",
  "created_by_name": "text",
  "created_at": "2026-01-20T23:21:30.944Z",
  "updated_at": "2026-01-20T23:21:30.944Z"
}

Update API Key

Delete API Key

Revoke an API key

delete

Revoke/delete an API key

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

accountIdstringRequired

Account ID

keyIdstring · uuidRequired

API Key ID

Responses

204

API key revoked successfully

401

Unauthorized

403

Forbidden

404

API key not found

delete

/user-service/api-keys/{keyId}

HTTPcURLJavaScriptPython

DELETE /v2/user-service/api-keys/{keyId} HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Rotate API Key

Rotate an API key

post

Generate a new secret for an existing API key, invalidating the old secret. Optionally update alias, description, and expiration date.

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

accountIdstringRequired

Account ID

keyIdstring · uuidRequired

API Key ID

Body

application/json

aliasstring | nullableOptional

Human-readable alias for the API key

descriptionstring | nullableOptional

Description of the API key's purpose

expires_atstring · date-time | nullableOptional

When the API key should expire (must be in the future, RFC3339 format)

Responses

200

API key rotated successfully

application/json

401

Unauthorized

403

Forbidden

404

API key not found

post

/user-service/api-keys/{keyId}/rotate

HTTPcURLJavaScriptPython

POST /v2/user-service/api-keys/{keyId}/rotate HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 77

{
  "alias": "text",
  "description": "text",
  "expires_at": "2026-01-20T23:21:30.944Z"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "key": "text",
  "is_legacy": false,
  "account_id": "text",
  "type": "TEAM",
  "user_id": "123e4567-e89b-12d3-a456-426614174000",
  "user_name": "text",
  "team_id": "123e4567-e89b-12d3-a456-426614174000",
  "team_name": "text",
  "alias": "text",
  "description": "text",
  "expires_at": "2026-01-20T23:21:30.944Z",
  "last_used": "2026-01-20T23:21:30.944Z",
  "created_by": "123e4567-e89b-12d3-a456-426614174000",
  "created_by_name": "text",
  "created_at": "2026-01-20T23:21:30.944Z",
  "updated_at": "2026-01-20T23:21:30.944Z"
}

Get API Key by Key Value

Roles

List Roles

List roles

get

Retrieve a list of roles for the specified account, including both account-specific roles and Firefly-managed (system-wide) roles. Firefly-managed roles have account_id as empty and are marked with fireflyManaged=true. For Firefly-managed roles, attached_users and team_names are filtered to show only those from the requesting account.

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

accountIdstringRequired

Account ID

Query parameters

limitinteger · min: 1 · max: 100Optional

Maximum number of roles to return

Default: 25

offsetintegerOptional

Number of roles to skip

Default: 0

searchstring · max: 255Optional

Search term to filter roles by name or description

Responses

200

Array of roles

application/json

400

Bad request

application/json

401

Unauthorized

403

Forbidden

get

/user-service/roles

HTTPcURLJavaScriptPython

GET /v2/user-service/roles HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "roles": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "account_id": "text",
      "name": "text",
      "description": "text",
      "integrationIds": [
        "integration-123",
        "integration-456"
      ],
      "providers": [
        "aws",
        "azure",
        "gcp"
      ],
      "scopes": [
        {
          "scope_id": 4,
          "scope_name": "inventory:read"
        }
      ],
      "attached_users": [
        {
          "name": "text",
          "profile_photo": "text"
        }
      ],
      "team_names": [
        "text"
      ],
      "firefly_managed": true,
      "created_at": "2026-01-20T23:21:30.944Z",
      "updated_at": "2026-01-20T23:21:30.944Z"
    }
  ],
  "total_count": 42
}

Create Role

Create a role

post

Create a new role with specified permissions

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

accountIdstringRequired

Account ID

Body

application/json

namestringRequired

Role name

descriptionstring | nullableOptional

Role description

integrationIdsstring[]Optional

Optional list of integration IDs to restrict role's access to specific integrations

Example: ["integration-123","integration-456"]

providersstring[]Optional

Optional list of provider types to restrict role's access to specific providers

Example: ["aws","azure","gcp"]

Responses

201

Created role

application/json

400

Bad request

application/json

401

Unauthorized

403

Forbidden

post

/user-service/roles

HTTPcURLJavaScriptPython

POST /v2/user-service/roles HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 151

{
  "name": "text",
  "description": "text",
  "integrationIds": [
    "integration-123",
    "integration-456"
  ],
  "providers": [
    "aws",
    "azure",
    "gcp"
  ],
  "scopes": [
    {
      "scope_id": 4
    }
  ]
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "account_id": "text",
  "name": "text",
  "description": "text",
  "integrationIds": [
    "integration-123",
    "integration-456"
  ],
  "providers": [
    "aws",
    "azure",
    "gcp"
  ],
  "scopes": [
    {
      "scope_id": 4,
      "scope_name": "inventory:read"
    }
  ],
  "attached_users": [
    {
      "name": "text",
      "profile_photo": "text"
    }
  ],
  "team_names": [
    "text"
  ],
  "firefly_managed": true,
  "created_at": "2026-01-20T23:21:30.944Z",
  "updated_at": "2026-01-20T23:21:30.944Z"
}

Update Role

Delete Role

Delete a role

delete

Delete a role from the system

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

accountIdstringRequired

Account ID

roleIdstring · uuidRequired

Role ID

Responses

204

Role deleted successfully

401

Unauthorized

403

Forbidden

404

Role not found

delete

/user-service/roles/{roleId}

HTTPcURLJavaScriptPython

DELETE /v2/user-service/roles/{roleId} HTTP/1.1
Host: api.firefly.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content