> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Update identity

> Replace identity tags. Omission preserves the existing tags; an empty object removes all tags.

<Info>
  Requires the IAM action **`email:UpdateIdentity`**. See [EMAIL permissions](/email/permissions) for the full list, what each one covers, and an example policy.
</Info>


## OpenAPI

````yaml /api-reference/specs/email.yaml patch /v1/identities/{identity_id}
openapi: 3.0.3
info:
  title: Basaltic Email API
  version: 1.0.0
  description: >
    Regional API for sending and receiving email, identities and DNS records,
    templates, configuration sets, IP pools, recipient rules, message content
    and attachments.


    Identities must be verified separately in every region. Create an identity,
    publish its dns_records, then request verification. Only verified identities
    can send or enable receiving.


    Request references accept a UUID, an account-unique name or a CRN of the
    expected resource type. Names are immutable. Malformed references or the
    wrong resource type/region return 400; missing or foreign-account references
    return 404. Resource paths use UUIDs. List filters are exact, account-scoped
    and applied before pagination; missing or foreign references return empty
    results.


    Sent and received message content expires after 30 days. Attachment objects
    follow their bucket lifecycle independently. Use Telemetry for aggregate
    metrics and the diagnostic endpoints for individual events and DMARC report
    records.
  contact:
    name: Basaltic Support
    email: ping@basaltic.sh
  license:
    name: Proprietary
    url: https://basaltic.sh/terms
servers:
  - url: https://email.{region}.basaltic.sh
    description: Regional API endpoint
    variables:
      region:
        default: sa-saopaulo-1
        description: Region code
security:
  - BearerAuth: []
tags:
  - name: Email
    description: Customer-facing email sending (regional).
paths:
  /v1/identities/{identity_id}:
    parameters:
      - $ref: '#/components/parameters/IdentityId'
    patch:
      tags:
        - Email
      summary: Update identity
      description: >-
        Replace identity tags. Omission preserves the existing tags; an empty
        object removes all tags.
      operationId: updateIdentity
      parameters:
        - name: identity_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateIdentityRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Permission denied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflicting state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Quota or rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Dependency unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    IdentityId:
      name: identity_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
  schemas:
    UpdateIdentityRequest:
      type: object
      properties:
        tags:
          $ref: '#/components/schemas/Tags'
    IdentityResponse:
      type: object
      required:
        - identity
      properties:
        identity:
          $ref: '#/components/schemas/Identity'
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - request_id
          properties:
            code:
              type: string
              description: Error code identifying the type of error
              example: INVALID_INPUT
            message:
              type: string
              description: Human-readable error message
              example: Invalid request parameters
            params:
              type: object
              additionalProperties: true
              description: >-
                Optional non-sensitive values for interpolation of localized
                errors, keyed by error code. Never present for server errors.
              example:
                instances: 2
                pools: 0
            request_id:
              type: string
              format: uuid
              description: Request ID for debugging
              example: 550e8400-e29b-41d4-a716-446655440000
    Tags:
      type: object
      additionalProperties:
        type: string
      example:
        environment: production
        team: backend
    Identity:
      type: object
      required:
        - id
        - crn
        - name
        - type
        - status
        - dkim_selector
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
        crn:
          type: string
        name:
          type: string
          description: >-
            Sender domain. Resource names must not start with the literal crn:
            prefix or be UUIDs (canonical, compact, braced, or urn:uuid: forms,
            in either case).
        type:
          type: string
          enum:
            - domain
        status:
          type: string
          enum:
            - pending
            - verified
            - failed
            - suspended
        dkim_selector:
          type: string
        dkim_pending_selector:
          type: string
        dkim_selector_old:
          type: string
        dkim_old_expires_at:
          type: string
          format: date-time
          nullable: true
        mail_from_domain:
          type: string
        mail_from_status:
          type: string
          enum:
            - pending
            - verified
            - failed
        mail_from_verified_at:
          type: string
          format: date-time
          nullable: true
        bimi_logo_url:
          type: string
        bimi_vmc_url:
          type: string
        bimi_status:
          type: string
          enum:
            - pending
            - verified
            - failed
        bimi_verified_at:
          type: string
          format: date-time
          nullable: true
        verified_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        suspended_reason:
          type: string
        suspended_at:
          type: string
          format: date-time
          nullable: true
        tags:
          $ref: '#/components/schemas/Tags'
        dns_records:
          type: array
          items:
            $ref: '#/components/schemas/DNSRecord'
    DNSRecord:
      type: object
      required:
        - purpose
        - type
        - name
        - value
        - required
        - group
      properties:
        purpose:
          type: string
          enum:
            - ownership
            - dkim
            - dkim_cname
            - dkim_pending
            - dkim_pending_cname
            - dkim_rotated_out
            - spf
            - dmarc
            - return_path
            - mail_from_mx
            - mail_from_spf
            - bimi
            - receiving_mx
        type:
          type: string
          enum:
            - TXT
            - CNAME
            - MX
        name:
          type: string
          description: FQDN to publish the record at.
        value:
          type: string
          description: >-
            Complete copyable record data: unquoted TXT content, CNAME target,
            or MX priority followed by host.
        required:
          type: boolean
          description: >-
            Required for this sending/receiving function. For an
            alternative_group, one alternative satisfies the requirement.
        group:
          type: string
          enum:
            - sending
            - receiving
        alternative_group:
          type: string
          description: >-
            Records sharing this value are alternatives. Publish exactly one
            record from a required alternative group; TXT and CNAME cannot
            coexist at the same name.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        An OAuth 2.0 bearer token, sent as `Authorization: Bearer <token>`.
        This is the recommended way to authenticate.

        Get one by exchanging a service account's access key pair at
        `POST /v1/oauth/token` with `grant_type=client_credentials`. It is the
        standard client-credentials grant, so any OAuth-aware library will
        obtain and refresh it for you.

        ```
        curl -s -u "$KEY_ID:$SECRET" -d grant_type=client_credentials \
          https://iam.basaltic.sh/v1/oauth/token
        ```

        Tokens last an hour by default. The same access key pair is separately
        your AWS SigV4 credential for the S3-compatible object endpoint, which
        speaks nothing else.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.