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

# Issue a leased token

> Mints a short-TTL bearer token an external service can use to call back into Marfa directly, without holding the connection's full runtime credential. The capability must be declared on the connection's integration manifest with `oauth_requirements: leased`; capabilities not declared as leased reject with `422`.

The `lease_token` field is returned **once** in the creation response; subsequent reads omit it. See [Integrations — OAuth proxy and leased tokens](/concepts/integrations#oauth-proxy-and-leased-tokens).



## OpenAPI

````yaml /openapi.json post /connections/{id}/lease-token
openapi: 3.1.0
info:
  title: Marfa API
  version: 4.2.0
  description: Typed data layer for structured personal data
servers: []
security: []
paths:
  /connections/{id}/lease-token:
    post:
      tags:
        - Connection Leased Tokens
      summary: Issue a leased token
      description: >-
        Mints a short-TTL bearer token an external service can use to call back
        into Marfa directly, without holding the connection's full runtime
        credential. The capability must be declared on the connection's
        integration manifest with `oauth_requirements: leased`; capabilities not
        declared as leased reject with `422`.


        The `lease_token` field is returned **once** in the creation response;
        subsequent reads omit it. See [Integrations — OAuth proxy and leased
        tokens](/concepts/integrations#oauth-proxy-and-leased-tokens).
      parameters:
        - schema:
            type: string
          required: true
          name: id
          in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                capability_id:
                  type: string
                  minLength: 1
                ttl_seconds:
                  type: integer
                  minimum: 1
                  maximum: 3600
                scopes:
                  type: array
                  items:
                    type: string
              required:
                - capability_id
      responses:
        '201':
          description: >-
            Lease issued. The `lease_token` field is returned ONCE; subsequent
            reads omit it.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  connection_id:
                    type: string
                  tenant_id:
                    type: string
                    nullable: true
                  capability_id:
                    type: string
                  scopes:
                    type: array
                    items:
                      type: string
                  expires_at:
                    type: string
                  revoked_at:
                    type: string
                    nullable: true
                  created_at:
                    type: string
                  lease_token:
                    type: string
                required:
                  - id
                  - connection_id
                  - tenant_id
                  - capability_id
                  - scopes
                  - expires_at
                  - revoked_at
                  - created_at
                  - lease_token
        '400':
          description: Invalid input or TTL out of range
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - validation_error
                          - missing_required_field
                          - lease_ttl_out_of_range
                      message:
                        type: string
                      details:
                        type: object
                        additionalProperties:
                          nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - unauthorized
                      message:
                        type: string
                      details:
                        type: object
                        additionalProperties:
                          nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        '403':
          description: Caller cannot manage this connection
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - forbidden
                      message:
                        type: string
                      details:
                        type: object
                        additionalProperties:
                          nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        '404':
          description: Connection not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - not_found
                      message:
                        type: string
                      details:
                        type: object
                        additionalProperties:
                          nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        '422':
          description: Manifest doesn't declare the capability as leased
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - lease_capability_not_declared
                      message:
                        type: string
                      details:
                        type: object
                        additionalProperties:
                          nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key or OAuth Token
      description: Pass an API key (marfa_k1_...) or OAuth access token (marfa_at_...)

````