abm-dev Organization API

openapi: 3.2.0
info:
  version: 2.0.0
  title: ABM.dev Organization API
  description: The account-based marketing API for AI agents. Search, Source, Enrich, and Create over B2B people and companies, every field cited with a source and confidence score.
  contact:
    name: ABM.dev
    url: https://abm.dev
servers:
- url: https://api.abm.dev
  description: Production
- url: https://api-dev.abm.dev
  description: Staging
security:
- ApiKeyAuth: []
tags:
- name: Organization
  description: Account and workspace management
paths:
  /v1/organizations/current:
    get:
      operationId: getCurrentOrganization
      tags:
      - Organization
      summary: Get current organization
      responses:
        '200':
          description: Current organization details
  /v1/organizations/signup:
    post:
      operationId: signupOrganization
      tags:
      - Organization
      summary: Provision organization for a new Clerk user
      description: Public endpoint for freshly-signed-up Clerk users. Creates a new organization and default workspace, or returns the existing one if the Clerk user/org already maps to an internal organization. Requires a valid Clerk Bearer token in the Authorization header — no pre-existing backend organization is required.
      security:
      - BearerAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                organizationName:
                  type: string
                  description: Optional display name for the organization. Defaults to the authenticated user's name or email prefix.
                name:
                  type: string
                  description: Optional display name for the owning user (fallback when the Clerk JWT does not carry a name claim).
                email:
                  type: string
                  format: email
                  description: Optional contact email (fallback when the Clerk JWT does not carry an email claim).
      responses:
        '200':
          description: Organization already existed — returning the existing record (idempotent response)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignupOrganizationResponse'
        '201':
          description: Organization successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignupOrganizationResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/api-keys:
    get:
      operationId: listApiKeys
      tags:
      - Organization
      summary: List API keys
      description: List all API keys belonging to the authenticated organization. The secret key value is never returned after creation — only metadata.
      responses:
        '200':
          description: List of API keys
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApiKeySummary'
    post:
      operationId: createApiKey
      tags:
      - Organization
      summary: Create API key
      description: Generate a new API key. The plaintext `key` field is only returned once in this response — store it securely.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  description: Human-readable label for the key
                description:
                  type: string
                  description: Optional long-form description
                environment:
                  type: string
                  enum:
                  - test
                  - live
                  default: live
                scopes:
                  type: array
                  items:
                    type: string
                  description: Permission scopes (e.g. `enrichment:read`, `enrichment:write`). Defaults to read-only if omitted.
                expiresAt:
                  type: string
                  format: date-time
                  description: Optional expiry timestamp
                allowedIpAddresses:
                  type: string
                  description: Comma-separated CIDR allow-list
                allowedReferrers:
                  type: string
                  description: Comma-separated referrer allow-list
                rateLimitPerMinute:
                  type: integer
                  description: Override the default rate limit for this key
      responses:
        '201':
          description: API key created. The `key` field is shown only in this response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateApiKeyResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
  /v1/api-keys/{keyId}:
    get:
      operationId: getApiKey
      tags:
      - Organization
      summary: Get API key metadata
      parameters:
      - name: keyId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: API key metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeySummary'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: revokeApiKey
      tags:
      - Organization
      summary: Revoke API key
      parameters:
      - name: keyId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  description: Audit log reason for the revocation
      responses:
        '204':
          description: API key revoked
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/api-keys/{keyId}/rotate:
    post:
      operationId: rotateApiKey
      tags:
      - Organization
      summary: Rotate API key
      description: Revokes the existing key and creates a new one with the same name and scopes. The new plaintext `key` is returned once — store it securely.
      parameters:
      - name: keyId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: API key rotated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateApiKeyResponse'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/organizations/workspaces:
    get:
      operationId: listWorkspaces
      tags:
      - Organization
      summary: List workspaces
      responses:
        '200':
          description: List of workspaces in the organization
    post:
      operationId: createWorkspace
      tags:
      - Organization
      summary: Create a workspace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                description:
                  type: string
      responses:
        '201':
          description: Workspace created
components:
  schemas:
    SignupOrganizationResponse:
      type: object
      properties:
        organizationId:
          type: string
          format: uuid
        organizationName:
          type: string
        organizationSlug:
          type: string
        clerkOrgId:
          type: string
          description: Clerk org ID (org_xxx) linked to this internal organization, if any
        clerkUserId:
          type: string
          description: Clerk user ID that triggered signup
        workspaceId:
          type: string
          format: uuid
          description: Default workspace ID created alongside the organization
        workspaceName:
          type: string
        created:
          type: boolean
          description: True when a new organization was provisioned by this request; false when an existing record was returned (idempotency)
    ApiKeySummary:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        prefix:
          type: string
          description: Non-secret display prefix for the key (e.g. `abm_live_...`)
        environment:
          type: string
          enum:
          - test
          - live
        scopes:
          type: array
          items:
            type: string
        createdAt:
          type: string
          format: date-time
        lastUsedAt:
          type: string
          format: date-time
        expiresAt:
          type: string
          format: date-time
        isActive:
          type: boolean
        revokedAt:
          type: string
          format: date-time
        allowedIpAddresses:
          type: string
        allowedReferrers:
          type: string
        rateLimitPerMinute:
          type: integer
    CreateApiKeyResponse:
      type: object
      properties:
        id:
          type: string
        key:
          type: string
          description: Plaintext API key — returned ONLY on creation/rotation. Store this securely; it cannot be retrieved again.
        name:
          type: string
        environment:
          type: string
          enum:
          - test
          - live
        scopes:
          type: array
          items:
            type: string
        createdAt:
          type: string
          format: date-time
        expiresAt:
          type: string
          format: date-time
        warning:
          type: string
          description: Reminder that the plaintext key is only shown once
  responses:
    Unauthorized:
      description: Missing or invalid API key
    NotFound:
      description: Resource not found
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              details:
                type: object
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Clerk-issued JWT. Used for dashboard/portal requests and for the `/v1/organizations/signup` bootstrap endpoint.
x-tagGroups:
- name: Core API
  tags:
  - Enrichment
  - People Finder
  - Campaigns
- name: Configuration
  tags:
  - Field Configuration
  - Enrichment Config
- name: Integrations
  tags:
  - LinkedIn
  - CRM
  - Webhooks
- name: Account
  tags:
  - Organization
  - Health