Management API - Users And Access

This page covers tenant selection, tenant membership, API tokens, automation keys, SAML SSO, SAML group mappings, and tenant settings.

Most endpoints on this page require the tenant header. The exceptions are called out in the relevant sections.

Tenant Selection

Use tenant selection endpoints before making tenant-scoped requests. These endpoints identify which tenant IDs the authenticated user can access.

List Tenants

Endpoint: GET /frontend/get_tenants

Required tenant header: No

Returns tenants available to the authenticated user.

Response:

{
  "tenants": [
    {
      "tenant_id": "9f1c0a4e7b8d4a4db52e6a6d5c5c1f11",
      "name": "Example Tenant",
      "plan": "TEAM"
    }
  ]
}

plan is one of FREE, TEAM, or ENTERPRISE.

Create Tenant

Endpoint: POST /frontend/create_tenant

Required tenant header: No

Creates a tenant for the authenticated user.

Request:

{
  "tenant_name": "Example Tenant"
}

Response:

{
  "success": true,
  "tenant_id": "9f1c0a4e7b8d4a4db52e6a6d5c5c1f11",
  "tenant_name": "Example Tenant"
}

Tenant names must be 5 to 30 characters and may contain letters, numbers, and spaces. Tenant creation can be blocked while the user is in a trial tenant or when the user's only tenant is a Free tenant.

Get Tenant Subscription

Endpoint: GET /frontend/get_tenant_subscription

Permission: Any authenticated tenant user

Returns subscription and tenant-level feature details for the current tenant.

Response:

{
  "subscription": "TEAM",
  "deletion": false,
  "enterprise_pricing": {
    "pricing_id": 3,
    "display_name": "Enterprise Annual",
    "amount_cents": 120000,
    "currency": "usd",
    "interval": "year"
  },
  "team_pricing": {
    "pricing_id": 2,
    "display_name": "Team Monthly",
    "amount_cents": 9900,
    "currency": "usd",
    "interval": "month"
  },
  "custom_limits": {
    "concurrent_builds": 2,
    "max_users": 20
  },
  "deployment_environments": false,
  "is_trial": false
}

Fields may be null or empty when no custom pricing or custom limits have been assigned.

User Management

User management endpoints require the Users & API Management permission. Adding users is available for Team and Enterprise tenants; Free tenants are limited to the tenant owner.

Default user limits are 20 users for Team tenants and 100 users for Enterprise tenants. Tenant-specific limits can override these defaults.

List Users And Permissions

Endpoint: GET /frontend/get_users_permissions

Permission: Any authenticated tenant user

Returns non-token users in the tenant and their permissions.

Response:

{
  "users": [
    {
      "user_id": "owner@example.com",
      "permissions": [
        "modify_configuration",
        "build_applications",
        "user_and_api_management"
      ]
    },
    {
      "user_id": "developer@example.com",
      "permissions": [
        "build_applications"
      ]
    }
  ]
}

Add User To Tenant

Endpoint: POST /frontend/add_user_to_tenant

Permission: user_and_api_management

Adds a user by email address. The request field is named user_id.

Request:

{
  "user_id": "newuser@example.com"
}

Response:

{
  "success": true
}

New users are added with no permissions. Assign permissions with /frontend/update_user_permissions after the user has been added.

Update User Permissions

Endpoint: POST /frontend/update_user_permissions

Permission: user_and_api_management

Replaces the user's permission set. Send permissions as a comma-separated string.

Request:

{
  "user_id": "developer@example.com",
  "permissions": "build_applications,modify_configuration"
}

Response:

{
  "success": true
}

Supported permission keys are:

Remove User From Tenant

Endpoint: POST /frontend/remove_user_from_tenant

Permission: user_and_api_management

Request:

{
  "user_id": "developer@example.com"
}

Response:

{
  "success": true
}

API Tokens

API tokens allow server-side systems to call the Management API without browser session credentials. API tokens require a Team or Enterprise tenant and the Users & API Management permission to create or delete.

Each tenant can have up to 20 API tokens.

Create API Token

Endpoint: POST /frontend/create_api_token

Permission: user_and_api_management

Request:

{}

Response:

{
  "token_key": "atk_abc123",
  "token_secret": "secret-value-shown-once"
}

Store token_secret immediately. It cannot be retrieved again.

New API tokens are created with no permissions. Grant permissions by updating the token's tenant-user permissions using the token key as the user_id.

Permission update example:

{
  "user_id": "atk_abc123",
  "permissions": "build_applications,modify_configuration"
}

Management API token authentication uses a Base64 encoded token_key:token_secret value:

TOKEN=$(printf '%s' "$TOKEN_KEY:$TOKEN_SECRET" | base64)

curl -sS https://app.apptego.com/frontend/get_tenants \
  -H "Authorization: Bearer $TOKEN"

List API Tokens

Endpoint: GET /frontend/get_api_tokens_permissions

Permission: Any authenticated tenant user on a Team or Enterprise tenant

Response:

{
  "tokens": [
    {
      "token_key": "atk_abc123",
      "permissions": [
        "build_applications"
      ],
      "created_by": "owner@example.com"
    }
  ]
}

Delete API Token

Endpoint: POST /frontend/delete_api_token

Permission: user_and_api_management

Request:

{
  "token_key": "atk_abc123"
}

Response:

{
  "success": true
}

Automation Keys

Automation keys are for the Automation API, not the Management API. They are managed through Management API endpoints and require a Team or Enterprise tenant.

Each tenant can have up to 10 automation keys.

List Automation Keys

Endpoint: GET /frontend/automation/keys

Permission: Any authenticated tenant user on a Team or Enterprise tenant

Response:

{
  "keys": [
    {
      "key_id": "auto_abc123",
      "name": "GitHub Actions",
      "enabled": true,
      "created_at": 1732740000,
      "last_used": null,
      "created_by": "owner@example.com"
    }
  ]
}

Create Automation Key

Endpoint: POST /frontend/automation/keys

Permission: user_and_api_management

name must be 2 to 50 characters.

Request:

{
  "name": "GitHub Actions"
}

Response:

{
  "key_id": "auto_abc123",
  "key_secret": "secret-value-shown-once"
}

Store key_secret immediately. It cannot be retrieved again.

Automation API requests use the raw key pair, not Base64 Management API token authentication:

curl -sS https://app.apptego.com/automate/status/build-id \
  -H "Authorization: Bearer $KEY_ID:$KEY_SECRET"

Toggle Automation Key

Endpoint: POST /frontend/automation/keys/toggle

Permission: user_and_api_management

Request:

{
  "key_id": "auto_abc123",
  "enabled": false
}

Response:

{
  "success": true
}

Delete Automation Key

Endpoint: POST /frontend/automation/keys/delete

Permission: user_and_api_management

Request:

{
  "key_id": "auto_abc123"
}

Response:

{
  "success": true
}

SAML SSO

SAML SSO is available for Enterprise tenants. Configuration endpoints require authenticated tenant access. Mutating configuration requires Tenant Settings; group mappings require Users & API Management for create/update.

The public browser SAML flow uses /frontend/saml/* endpoints. The endpoints below are the authenticated Management API endpoints for configuring that flow.

Get SAML Settings

Endpoint: GET /frontend/saml_settings

Permission: Any authenticated tenant user on an Enterprise tenant

Response:

{
  "entity_id": "https://idp.example.com/saml",
  "sso_url": "https://idp.example.com/sso",
  "sp_entity_id": "https://app.apptego.com/frontend/saml/metadata/9f1c0a4e7b8d4a4db52e6a6d5c5c1f11",
  "acs_url": "https://app.apptego.com/frontend/saml/acs/9f1c0a4e7b8d4a4db52e6a6d5c5c1f11",
  "sls_url": "https://app.apptego.com/frontend/saml/sls/9f1c0a4e7b8d4a4db52e6a6d5c5c1f11",
  "use_group_authorization": true,
  "group_attribute_name": "groups",
  "enabled": true,
  "enforce_sso_only": false,
  "breakglass_account": "owner@example.com"
}

When SAML is not configured, string fields are empty, booleans default to false, and breakglass_account is null.

Update SAML Settings

Endpoint: POST /frontend/saml_settings

Permission: modify_tenant_settings

Required fields are entity_id, sso_url, x509_cert, sp_entity_id, acs_url, and sls_url.

Request:

{
  "entity_id": "https://idp.example.com/saml",
  "sso_url": "https://idp.example.com/sso",
  "x509_cert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
  "sp_entity_id": "https://app.apptego.com/frontend/saml/metadata/9f1c0a4e7b8d4a4db52e6a6d5c5c1f11",
  "acs_url": "https://app.apptego.com/frontend/saml/acs/9f1c0a4e7b8d4a4db52e6a6d5c5c1f11",
  "sls_url": "https://app.apptego.com/frontend/saml/sls/9f1c0a4e7b8d4a4db52e6a6d5c5c1f11",
  "use_group_authorization": true,
  "group_attribute_name": "groups",
  "enabled": true,
  "enforce_sso_only": false,
  "breakglass_account": "owner@example.com"
}

Response:

{
  "success": true,
  "message": "SAML configuration updated"
}

entity_id, sso_url, sp_entity_id, acs_url, and sls_url must be HTTPS URLs. When enforce_sso_only is enabled, the breakglass account must be a tenant user with Users & API Management.

Parse IdP Metadata

Endpoint: POST /frontend/saml_parse_metadata

Permission: modify_tenant_settings

Parses SAML 2.0 IdP metadata XML up to 256 KB and returns the fields needed for configuration.

Request:

{
  "metadata_xml": "<EntityDescriptor ...>...</EntityDescriptor>"
}

Response:

{
  "entity_id": "https://idp.example.com/saml",
  "sso_url": "https://idp.example.com/sso",
  "x509_cert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
}

Delete SAML Settings

Endpoint: DELETE /frontend/saml_settings

Permission: modify_tenant_settings

Deletes SAML configuration and associated group mappings for the tenant.

Response:

{
  "success": true,
  "message": "SAML configuration deleted"
}

List SAML Group Mappings

Endpoint: GET /frontend/saml_groups

Permission: Any authenticated tenant user on an Enterprise tenant

Response:

{
  "groups": [
    {
      "id": 42,
      "group_name": "AppTego-Admins",
      "permissions": [
        "modify_configuration",
        "user_and_api_management"
      ],
      "description": "Administrators from the IdP",
      "enabled": true,
      "created_at": 1732740000,
      "updated_at": 1732741200
    }
  ]
}

Create Or Update SAML Group Mapping

Endpoint: POST /frontend/saml_groups

Permission: user_and_api_management

Omit id to create a mapping. Include id to update an existing mapping. Set enabled to false to disable a mapping.

Request:

{
  "id": 42,
  "group_name": "AppTego-Admins",
  "permissions": [
    "modify_configuration",
    "user_and_api_management"
  ],
  "description": "Administrators from the IdP",
  "enabled": true
}

Response:

{
  "success": true,
  "message": "SAML group mapping saved"
}

Tenant Settings

Tenant settings endpoints require the Tenant Settings permission.

Rename Tenant

Endpoint: POST /frontend/modify_tenant_details

Permission: modify_tenant_settings

Request:

{
  "tenant_name": "Updated Tenant Name"
}

Response:

{
  "success": true
}

Tenant names must be 5 to 30 characters and may contain letters, numbers, and spaces. A tenant can be renamed up to five times per day.

Enable Or Disable Deployment Environments

Endpoint: POST /frontend/update_deployment_environments

Permission: modify_tenant_settings

Deployment environments are available to Team and Enterprise tenants.

Request:

{
  "enabled": true
}

Response:

{
  "success": true,
  "deployment_environments": true
}

Delete Tenant

Endpoint: POST /frontend/delete_tenant

Permission: modify_tenant_settings

Marks the current tenant for deletion. The tenant is selected by the tenant header.

Request:

{}

Response:

{
  "success": true
}

Restore Tenant

Endpoint: POST /frontend/restore_tenant

Permission: modify_tenant_settings

Restores the current tenant if it is pending deletion. The tenant is selected by the tenant header.

Request:

{}

Response:

{
  "success": true
}

Common Errors