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

# Create a token connection

> Encrypts a one-way token write and returns only safe connection metadata.



## OpenAPI

````yaml /openapi/platform.v1.json post /v1/connections
openapi: 3.0.3
info:
  description: Public platform API for catalog and proxied data-plane routes.
  title: Matrices Platform API
  version: v1
servers:
  - url: https://api.matrices.com
security: []
tags:
  - description: Authenticated bearer credential context.
    name: auth
    x-group: Auth
  - description: Write-only provider credentials with safe connection metadata.
    name: connections
    x-group: Connections
  - description: Materialized workspace principals and active agent counts.
    name: identities
    x-group: Identities
  - description: Remote MCP server registrations.
    name: toolsets
    x-group: Toolsets
  - description: Named allow-only agent tool permissions.
    name: roles
    x-group: Roles
  - description: Client-executed tool calls.
    name: tools
    x-group: Tools
  - description: Reusable agent behavior profiles.
    name: profiles
    x-group: Profiles
  - description: Workspace-owned agent identities.
    name: agents
    x-group: Agents
  - description: Immutable private image inputs.
    name: images
    x-group: Images
  - description: Public model catalog.
    name: models
    x-group: Models
  - description: Running agent threads.
    name: threads
    x-group: Threads
  - description: Agent schedules.
    name: schedules
    x-group: Schedules
  - description: Workspace append-only feeds.
    name: feeds
    x-group: Feeds
  - description: Agent subscriptions over workspace feeds.
    name: subscriptions
    x-group: Subscriptions
  - description: Agent-private and workspace-shared durable memory notes.
    name: memory
    x-group: Memory
  - description: Thread messages.
    name: messages
    x-group: Messages
  - description: Thread event log data.
    name: events
    x-group: Events
  - description: Runtime hook audit and wait resolution.
    name: hooks
    x-group: Hooks
paths:
  /v1/connections:
    post:
      tags:
        - connections
      summary: Create a token connection
      description: >-
        Encrypts a one-way token write and returns only safe connection
        metadata.
      operationId: CreateConnection
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectionCreateTokenRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionResponse'
          description: Replayed connection creation.
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionResponse'
          description: Connection created.
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '503':
          $ref: '#/components/responses/CatalogUnavailable'
      security:
        - APIKeyBearer: []
components:
  schemas:
    ConnectionCreateTokenRequest:
      additionalProperties: false
      properties:
        name:
          type: string
        owner:
          $ref: '#/components/schemas/ConnectionOwner'
        provider:
          $ref: '#/components/schemas/AuthProvider'
        remoteSubject:
          type: string
        remoteTenant:
          type: string
        token:
          format: password
          type: string
          writeOnly: true
      required:
        - provider
        - name
        - owner
        - token
      type: object
    ConnectionResponse:
      properties:
        connection:
          $ref: '#/components/schemas/Connection'
      required:
        - connection
      type: object
    ConnectionOwner:
      discriminator:
        mapping:
          identity: '#/components/schemas/IdentityConnectionOwner'
          workspace: '#/components/schemas/WorkspaceConnectionOwner'
        propertyName: type
      oneOf:
        - $ref: '#/components/schemas/WorkspaceConnectionOwner'
        - $ref: '#/components/schemas/IdentityConnectionOwner'
    AuthProvider:
      enum:
        - google
        - slack
        - notion
        - github
        - linear
        - vercel
        - figma
        - stripe
        - posthog
        - datadog
        - cloudflare
        - apollo
      type: string
    Connection:
      description: Safe connection metadata. Credential material is never returned.
      properties:
        createdAt:
          format: date-time
          type: string
        id:
          type: string
        kind:
          $ref: '#/components/schemas/ConnectionKind'
        name:
          type: string
        namespace:
          type: string
        owner:
          $ref: '#/components/schemas/ConnectionOwner'
        products:
          items:
            $ref: '#/components/schemas/ConnectionProduct'
          type: array
        provider:
          $ref: '#/components/schemas/AuthProvider'
        remoteResource:
          $ref: '#/components/schemas/ConnectionResource'
        remoteSubject:
          type: string
        remoteTenant:
          type: string
        revokedAt:
          format: date-time
          type: string
        status:
          $ref: '#/components/schemas/ConnectionStatus'
        updatedAt:
          format: date-time
          type: string
        version:
          format: int64
          minimum: 1
          type: integer
        workspaceId:
          type: string
      required:
        - id
        - workspaceId
        - kind
        - name
        - owner
        - status
        - version
        - createdAt
        - updatedAt
      type: object
    ErrorResponse:
      properties:
        attemptsRemaining:
          type: integer
        code:
          type: string
        error:
          type: string
        message:
          type: string
        retryAfterSeconds:
          type: integer
      required:
        - error
        - message
      type: object
    IdentityConnectionOwner:
      additionalProperties: false
      properties:
        identity:
          $ref: '#/components/schemas/Identity'
        type:
          enum:
            - identity
          type: string
      required:
        - type
        - identity
      type: object
    WorkspaceConnectionOwner:
      additionalProperties: false
      properties:
        type:
          enum:
            - workspace
          type: string
      required:
        - type
      type: object
    ConnectionKind:
      description: Credential shape held by a connection.
      enum:
        - token
        - oauth
      type: string
    ConnectionProduct:
      additionalProperties: false
      properties:
        namespace:
          type: string
        presets:
          items:
            $ref: '#/components/schemas/ProviderAccessPreset'
          type: array
      required:
        - namespace
        - presets
      type: object
    ConnectionResource:
      additionalProperties: false
      properties:
        id:
          type: string
        kind:
          $ref: '#/components/schemas/ConnectionResourceKind'
        name:
          type: string
      required:
        - kind
        - id
        - name
      type: object
    ConnectionStatus:
      enum:
        - ready
        - needs_reauth
        - revoked
      type: string
    Identity:
      description: >-
        Provenance identity. Surrounding whitespace is trimmed on input; values
        may contain at most 512 UTF-8 bytes and no Unicode control characters.
      type: string
    ProviderAccessPreset:
      enum:
        - default
        - read_only
        - full
      type: string
    ConnectionResourceKind:
      enum:
        - workspace
        - project
      type: string
  responses:
    BadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Invalid request.
    NotFound:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Resource not found.
    Conflict:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Request conflicts with the thread's current state.
    CatalogUnavailable:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Platform catalog database is not configured or unavailable.
  securitySchemes:
    APIKeyBearer:
      scheme: bearer
      type: http

````

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