Create org service account

POST /api/v1/organizations/{id}/service-accounts
Bearer auth

Creates an org-scoped customer service account and returns its secret once. roles is required and accepts at most one non-blank name: ORG_GROUP_CREATOR or ORG_READ_ONLY. Legacy Agent Engine names (ORG_ADMIN, ORG_MEMBER) are still accepted. role_assignments echoes the stored Agent Engine role. Requires ORG_ADMIN.

Path parameters

  • id string Required

    Organization ID

application/json

Body Required

Create request

  • description string

    Maximum length is 500.

  • ip_access_list array[string]

    Optional IP/CIDR allowlist. Empty or omitted means unrestricted. At most 100 entries.

    Not more than 100 elements.

  • name string Required

    Maximum length is 100.

  • roles array[string] Required

    Roles is the initial role set. Exactly one role is required. Organization accounts accept ORG_GROUP_CREATOR or ORG_READ_ONLY. Project accounts accept PROJECT_OWNER, PROJECT_READ_ONLY, or AGENT_DEVELOPER. Legacy Agent Engine names (ORG_ADMIN, ORG_MEMBER, PROJECT_MEMBER) are still accepted. role_assignments echoes the stored Agent Engine role those names resolve to.

    At least 1 but not more than 1 element.

  • secret_expires_after_hours integer

    Optional secret TTL in hours. Defaults to 2160 (90 days) when omitted.

Responses

  • 406

    Unsupported or malformed API version, an operation unavailable in the selected published contract, or an unacceptable representation (including unsupported media-type parameters or excluded SSE). Existing authentication, authorization, and rate-limit failures take precedence.

    Hide response attributes Show response attributes object
    • badRequestDetail object

      Optional validation details defined by the standard error schema; API negotiation errors do not emit this field.

      Hide badRequestDetail attribute Show badRequestDetail attribute object
      • fields array[object]

        Fields with validation failures.

        Hide fields attributes Show fields attributes object

        A field and its validation failure.

        • description string Required

          Human-readable validation failure.

        • field string Required

          Name or path of the invalid request field.

    • detail string Required

      Human-readable error details.

    • error integer Required

      HTTP status code.

    • errorCode string Required

      Machine-readable error code.

    • parameters array[string]

      Request parameter names associated with the error; omitted when none apply.

    • reason string Required

      HTTP status reason phrase.

    Hide response attributes Show response attributes object
    • badRequestDetail object

      Optional validation details defined by the standard error schema; API negotiation errors do not emit this field.

      Hide badRequestDetail attribute Show badRequestDetail attribute object
      • fields array[object]

        Fields with validation failures.

        Hide fields attributes Show fields attributes object

        A field and its validation failure.

        • description string Required

          Human-readable validation failure.

        • field string Required

          Name or path of the invalid request field.

    • detail string Required

      Human-readable error details.

    • error integer Required

      HTTP status code.

    • errorCode string Required

      Machine-readable error code.

    • parameters array[string]

      Request parameter names associated with the error; omitted when none apply.

    • reason string Required

      HTTP status reason phrase.
  • 201

    Created

    Hide response attributes Show response attributes object
    • client_secret string
    • service_account object
      Hide service_account attributes Show service_account attributes object
      • active_secret object
        Hide active_secret attributes Show active_secret attributes object
        • created_at string
        • expires_at string
        • last_used_at string
        • masked_value string
      • client_id string
      • created_at string
      • description string
      • id string
      • ip_access_list array[string]
      • is_active boolean
      • is_system_managed boolean
      • name string
      • org_id string
      • owner string
      • project_id string
      • role_assignments array[object]
        Hide role_assignments attributes Show role_assignments attributes object
        • org_id string
        • project_id string
        • role string
      • type string
      • updated_at string
    Hide response attributes Show response attributes object
    • client_secret string
    • service_account object
      Hide service_account attributes Show service_account attributes object
      • active_secret object
        Hide active_secret attributes Show active_secret attributes object
        • created_at string
        • expires_at string
        • last_used_at string
        • masked_value string
      • client_id string
      • created_at string
      • description string
      • id string
      • ip_access_list array[string]
      • is_active boolean
      • is_system_managed boolean
      • name string
      • org_id string
      • owner string
      • project_id string
      • role_assignments array[object]
        Hide role_assignments attributes Show role_assignments attributes object
        • org_id string
        • project_id string
        • role string
      • type string
      • updated_at string
  • 400

    Bad Request

    Hide response attributes Show response attributes object
    • code string
    • error string
    • success boolean
    Hide response attributes Show response attributes object
    • code string
    • error string
    • success boolean
  • 403

    Forbidden

    Hide response attributes Show response attributes object
    • code string
    • error string
    • success boolean
    Hide response attributes Show response attributes object
    • code string
    • error string
    • success boolean
  • 404

    Not Found

    Hide response attributes Show response attributes object
    • code string
    • error string
    • success boolean
    Hide response attributes Show response attributes object
    • code string
    • error string
    • success boolean
  • 409

    Conflict

    Hide response attributes Show response attributes object
    • code string
    • error string
    • success boolean
    Hide response attributes Show response attributes object
    • code string
    • error string
    • success boolean
  • 429

    Too Many Requests

    Hide headers attribute Show headers attribute
    • Retry-After string

      Seconds to wait before retrying

    Hide response attributes Show response attributes object
    • code string
    • error string
    • success boolean
    Hide response attributes Show response attributes object
    • code string
    • error string
    • success boolean
  • 500

    Internal Server Error

    Hide response attributes Show response attributes object
    • code string
    • error string
    • success boolean
    Hide response attributes Show response attributes object
    • code string
    • error string
    • success boolean
  • 503

    Service Unavailable

    Hide headers attribute Show headers attribute
    • Retry-After string

      Seconds to wait before retrying

    Hide response attributes Show response attributes object
    • code string
    • error string
    • success boolean
    Hide response attributes Show response attributes object
    • code string
    • error string
    • success boolean
POST /api/v1/organizations/{id}/service-accounts 
curl \
 --request POST 'https://agentengine.mongodb.com/api/v1/organizations/{id}/service-accounts' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{
  "description": "string",
  "ip_access_list": [
    "string"
  ],
  "name": "string",
  "roles": [
    "string"
  ],
  "secret_expires_after_hours": 42
}'
Request examples 
{
  "description": "string",
  "ip_access_list": [
    "string"
  ],
  "name": "string",
  "roles": [
    "string"
  ],
  "secret_expires_after_hours": 42
}
Response examples (406) 
{
  "detail": "This operation is not available in API version 2026-09-20-preview.",
  "error": 406,
  "errorCode": "OPERATION_NOT_IN_API_VERSION",
  "parameters": [
    "Accept"
  ],
  "reason": "Not Acceptable"
}
{
  "detail": "This operation supports text/event-stream, which the Accept header excludes. Remove unsupported media-type parameters or accept this type with a positive q value.",
  "error": 406,
  "errorCode": "UNACCEPTABLE_MEDIA_TYPE",
  "parameters": [
    "Accept"
  ],
  "reason": "Not Acceptable"
}
{
  "detail": "The requested API version is not supported. Supported versions: 2026-09-20-preview.",
  "error": 406,
  "errorCode": "UNSUPPORTED_API_VERSION",
  "parameters": [
    "Accept"
  ],
  "reason": "Not Acceptable"
}
Response examples (406) 
{
  "detail": "This operation is not available in API version 2026-09-20-preview.",
  "error": 406,
  "errorCode": "OPERATION_NOT_IN_API_VERSION",
  "parameters": [
    "Accept"
  ],
  "reason": "Not Acceptable"
}
Response examples (201) 
{
  "client_secret": "string",
  "service_account": {
    "active_secret": {
      "created_at": "string",
      "expires_at": "string",
      "last_used_at": "string",
      "masked_value": "string"
    },
    "client_id": "string",
    "created_at": "string",
    "description": "string",
    "id": "string",
    "ip_access_list": [
      "string"
    ],
    "is_active": true,
    "is_system_managed": true,
    "name": "string",
    "org_id": "string",
    "owner": "string",
    "project_id": "string",
    "role_assignments": [
      {
        "org_id": "string",
        "project_id": "string",
        "role": "string"
      }
    ],
    "type": "string",
    "updated_at": "string"
  }
}
Response examples (201) 
{
  "client_secret": "string",
  "service_account": {
    "active_secret": {
      "created_at": "string",
      "expires_at": "string",
      "last_used_at": "string",
      "masked_value": "string"
    },
    "client_id": "string",
    "created_at": "string",
    "description": "string",
    "id": "string",
    "ip_access_list": [
      "string"
    ],
    "is_active": true,
    "is_system_managed": true,
    "name": "string",
    "org_id": "string",
    "owner": "string",
    "project_id": "string",
    "role_assignments": [
      {
        "org_id": "string",
        "project_id": "string",
        "role": "string"
      }
    ],
    "type": "string",
    "updated_at": "string"
  }
}
Response examples (400) 
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (400) 
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (403) 
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (403) 
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (404) 
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (404) 
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (409) 
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (409) 
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (429) 
# Headers
Retry-After: string

# Payload
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (429) 
# Headers
Retry-After: string

# Payload
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (500) 
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (500) 
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (503) 
# Headers
Retry-After: string

# Payload
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (503) 
# Headers
Retry-After: string

# Payload
{
  "code": "string",
  "error": "string",
  "success": true
}