openapi: 3.0.2
info:
  title: Service Accounts API
  description: Endpoints for managing service accounts programmatically.
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  version: 1.0.0
  contact:
    url: https://mixpanel.com/get-support
servers:
- url: https://{regionAndDomain}.com/api/app
  description: Mixpanel's application API server.
  variables:
    regionAndDomain:
      default: mixpanel
      enum:
      - mixpanel
      - eu.mixpanel
      - in.mixpanel
      description: "The server location to be used:\n  * `mixpanel` - The default (US) servers used for most projects\n  *\
        \ `eu.mixpanel` - EU servers if you are enrolled in EU Data Residency\n  * `in.mixpanel` - India servers if you are\
        \ enrolled in India Data Residency\n"
security:
- ServiceAccount: []
tags:
- name: Create Service Accounts
  description: Operations to add service accounts to an organization
- name: Delete Service Accounts
  description: Remove a service account from an organization
- name: Project Membership
  description: Add/remove service accounts to/from projects
- name: Retrieve Service Accounts
  description: Get details about an organization's service account
paths:
  /organizations/{organizationId}/service-accounts:
    parameters:
    - in: path
      name: organizationId
      schema:
        type: integer
      required: true
      description: 'Your organization id (eg: 12345)'
    get:
      tags:
      - Retrieve Service Accounts
      summary: List Service Accounts
      description: Return a list of all service accounts for your organization
      operationId: list-service-accounts
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListServiceAccountsResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Details about the error that occurred
                  status:
                    type: string
                    enum:
                    - error
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Details about the error that occurred
                  status:
                    type: string
                    enum:
                    - error
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Details about the error that occurred
                  status:
                    type: string
                    enum:
                    - error
    post:
      tags:
      - Create Service Accounts
      summary: Create Service Account
      description: Create a new service account for your organization and optionally add it to one or more projects in your
        organization
      operationId: create-service-account
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateServiceAccountRequest'
      responses:
        '201':
          description: Service account successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateServiceAccountResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Details about the error that occurred
                  status:
                    type: string
                    enum:
                    - error
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Details about the error that occurred
                  status:
                    type: string
                    enum:
                    - error
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Details about the error that occurred
                  status:
                    type: string
                    enum:
                    - error
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Details about the error that occurred
                  status:
                    type: string
                    enum:
                    - error
  /organizations/{organizationId}/service-accounts/{serviceAccountId}:
    parameters:
    - in: path
      name: organizationId
      schema:
        type: integer
      required: true
      description: 'Your organization id (eg: 12345)'
    - $ref: '#/components/parameters/serviceAccountId'
    get:
      tags:
      - Retrieve Service Accounts
      summary: Get Service Account
      description: Return service account details by id
      operationId: get-service-account
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceAccountRead'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Details about the error that occurred
                  status:
                    type: string
                    enum:
                    - error
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Details about the error that occurred
                  status:
                    type: string
                    enum:
                    - error
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Details about the error that occurred
                  status:
                    type: string
                    enum:
                    - error
    delete:
      tags:
      - Delete Service Accounts
      summary: Delete Service Account
      description: Removes the service account from all associated projects and deletes it from the organization
      operationId: delete-service-account
      responses:
        '200':
          description: Successfully deleted service account
          content:
            application/json:
              schema:
                type: object
                example:
                  status: ok
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Details about the error that occurred
                  status:
                    type: string
                    enum:
                    - error
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Details about the error that occurred
                  status:
                    type: string
                    enum:
                    - error
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Details about the error that occurred
                  status:
                    type: string
                    enum:
                    - error
  /projects/{projectId}/service-accounts:
    parameters:
    - in: path
      name: projectId
      schema:
        type: integer
      required: true
      description: 'Your project id (eg: 12345)'
    get:
      tags:
      - Project Membership
      summary: List Service Accounts For Project
      description: Retrieve a list of service accounts that are members of the specified project
      operationId: list-project-service-accounts
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListServiceAccountsForProjectResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Details about the error that occurred
                  status:
                    type: string
                    enum:
                    - error
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Details about the error that occurred
                  status:
                    type: string
                    enum:
                    - error
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Details about the error that occurred
                  status:
                    type: string
                    enum:
                    - error
  /organizations/{organizationId}/service-accounts/add-to-project:
    parameters:
    - in: path
      name: organizationId
      schema:
        type: integer
      required: true
      description: 'Your organization id (eg: 12345)'
    post:
      tags:
      - Project Membership
      summary: Add Service Accounts To Projects
      description: Adds a list of service account ids to a list of project ids with the specified role
      operationId: add-service-accounts-to-projects
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddServiceAccountsToProjectsRequest'
      responses:
        '200':
          description: Service accounts added to projects
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: '"ok" if the request succeeded, "error" otherwise.'
                    example: ok
                    enum:
                    - ok
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Details about the error that occurred
                  status:
                    type: string
                    enum:
                    - error
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Details about the error that occurred
                  status:
                    type: string
                    enum:
                    - error
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Details about the error that occurred
                  status:
                    type: string
                    enum:
                    - error
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Details about the error that occurred
                  status:
                    type: string
                    enum:
                    - error
  /organizations/{organizationId}/service-accounts/remove-from-project:
    parameters:
    - in: path
      name: organizationId
      schema:
        type: integer
      required: true
      description: 'Your organization id (eg: 12345)'
    post:
      tags:
      - Project Membership
      summary: Remove Service Accounts From Projects
      description: Removes a list of service account ids from a list of project ids
      operationId: remove-service-accounts-from-projects
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RemoveServiceAccountsFromProjectsRequest'
      responses:
        '200':
          description: Service accounts removed from projects
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: '"ok" if the request succeeded, "error" otherwise.'
                    example: ok
                    enum:
                    - ok
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Details about the error that occurred
                  status:
                    type: string
                    enum:
                    - error
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Details about the error that occurred
                  status:
                    type: string
                    enum:
                    - error
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Details about the error that occurred
                  status:
                    type: string
                    enum:
                    - error
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Details about the error that occurred
                  status:
                    type: string
                    enum:
                    - error
components:
  securitySchemes:
    ServiceAccount:
      type: http
      scheme: basic
      description: Service Account
    ProjectSecret:
      type: http
      scheme: basic
      description: Project Secret
    OAuthToken:
      type: http
      scheme: bearer
      description: OAuth Token
  parameters:
    serviceAccountId:
      in: path
      name: serviceAccountId
      description: The id of an existing Service Account
      schema:
        type: integer
      required: true
  schemas:
    RoleEnum:
      type: string
      description: The service account's role
      enum:
      - owner
      - admin
      - analyst
      - consumer
    ServiceAccountRead:
      type: object
      properties:
        id:
          type: integer
          description: The unique identifier for this service account
        username:
          type: string
          description: The username of the service account
        last_used:
          type: string
          format: date-time
          description: The date/time this service account was last used for authentication
        expires:
          type: string
          format: date-time
          description: The date/time this service account will expire
        creator:
          type: integer
          description: The Mixpanel user id that created this service account
        created:
          type: string
          format: date-time
          description: The date/time this service account was created
        user:
          type: integer
          description: The Mixpanel user id that this serivce account represents. This is only used internally and is safe
            to ignore.
    ServiceAccountWrite:
      type: object
      required:
      - username
      properties:
        username:
          type: string
          description: A descriptive name for the service account
        role:
          $ref: '#/components/schemas/RoleEnum'
        expires:
          type: string
          format: date-time
          description: The datetime that the service account should expire
        projects:
          type: array
          description: A list of projects to make this serivce account a member of
          items:
            type: object
            properties:
              id:
                type: integer
                description: The project id to add the service account to
              role:
                $ref: '#/components/schemas/RoleEnum'
    CreateServiceAccountRequest:
      $ref: '#/components/schemas/ServiceAccountWrite'
    AddServiceAccountsToProjectsRequest:
      type: object
      properties:
        projects:
          type: array
          description: List of project/roles
          items:
            type: object
            properties:
              id:
                type: integer
                description: The project id to add the service account to
              role:
                $ref: '#/components/schemas/RoleEnum'
            required:
            - id
            - role
        service_account_ids:
          type: array
          description: List of service account ids
          items:
            type: integer
      required:
      - projects
      - service_account_ids
    RemoveServiceAccountsFromProjectsRequest:
      type: object
      properties:
        projects:
          type: array
          description: A list of projects and service accounts to remove
          items:
            type: object
            properties:
              id:
                type: integer
                description: The project id to remove the service account from
              service_account_ids:
                type: array
                description: The list of service account ids to remove from the project
                items:
                  type: integer
            required:
            - id
            - service_account_ids
      required:
      - projects
    CreateServiceAccountResponse:
      type: object
      properties:
        results:
          allOf:
          - type: object
            properties:
              token:
                type: string
                description: 'The secret key for this service account. Note: This cannot be recovered so you should immediately
                  store this somewhere secure.'
          - $ref: '#/components/schemas/ServiceAccountRead'
        status:
          type: string
          description: '"ok" if the request succeeded, "error" otherwise.'
          example: ok
          enum:
          - ok
    ListServiceAccountsResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/ServiceAccountRead'
        status:
          type: string
          description: '"ok" if the request succeeded, "error" otherwise.'
          example: ok
          enum:
          - ok
    ListServiceAccountsForProjectResponse:
      type: object
      properties:
        results:
          type: array
          items:
            allOf:
            - $ref: '#/components/schemas/ServiceAccountRead'
            - type: object
              properties:
                hasSensitiveAccess:
                  type: boolean
                  description: Wether or not the service account has access to classified data. See https://help.mixpanel.com/hc/en-us/articles/360044295131-Data-Classification
                role:
                  $ref: '#/components/schemas/RoleEnum'
                role_order:
                  type: integer
                  description: This is only used internally and is safe to ignore
                target_type:
                  type: string
                  description: The grant type that gives the service account membership to the project (usually "individual")
                  enum:
                  - individual
                  - team
                  - organization
                email:
                  type: string
                  description: This is only used internally and is safe to ignore
        status:
          type: string
          description: '"ok" if the request succeeded, "error" otherwise.'
          example: ok
          enum:
          - ok
x-explorer-enabled: true
x-proxy-enabled: true
x-samples-enabled: true
x-samples-languages:
- curl
- node
- ruby
- javascript
- python