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

# Create a link

> Creates a page where the user signs in to Circuit, picks which wallets your app may use and approves with their passkey. Open the returned `url` in a real browser, then check the link until it is approved. A link expires after five minutes. Needs no permit.



## OpenAPI

````yaml /partner-openapi.gen.json post /partner/v0.1/links
openapi: 3.1.0
info:
  title: Circuit partner API
  version: '0.1'
servers:
  - url: https://api.circuit.org
security: []
paths:
  /partner/v0.1/links:
    post:
      summary: Create a link
      description: >-
        Creates a page where the user signs in to Circuit, picks which wallets
        your app may use and approves with their passkey. Open the returned
        `url` in a real browser, then check the link until it is approved. A
        link expires after five minutes. Needs no permit.
      operationId: createLink
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                app:
                  description: >-
                    Your app id, as Circuit registered it. The user sees your
                    app's name when they approve.
                  type: string
                  examples:
                    - pinewood
                public_key:
                  description: >-
                    Your X25519 public key as 64 hex characters. Circuit
                    encrypts the permit to this key.
                  type: string
                  examples:
                    - >-
                      8f2c1d6e4b3a59078c1e2d3f4a5b6c7d8e9f00112233445566778899aabbccdd
                return_url:
                  description: >-
                    Where Circuit sends the user after they approve. It must
                    start with one of the URLs registered for your app.
                    Optional.
                  type:
                    - string
                    - 'null'
                  examples:
                    - https://yourapp.com/linked
              additionalProperties: false
              required:
                - app
                - public_key
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                description: >-
                  A page where the user approves your app. Once they do, it
                  holds their permit.
                type: object
                properties:
                  id:
                    description: The link's id, starting with `lnk_`.
                    type: string
                  url:
                    description: >-
                      Open this in a real browser so the user can sign in, pick
                      wallets and approve.
                    type: string
                  status:
                    $ref: '#/components/schemas/LinkStatus'
                  permit:
                    description: >-
                      The user's permit, encrypted to your public key, once
                      `status` is `approved`. It is base64url of a 32-byte
                      ephemeral X25519 public key, a 12-byte IV and the
                      AES-256-GCM ciphertext. Null until then.
                    type:
                      - string
                      - 'null'
                  expires_at:
                    $ref: '#/components/schemas/Timestamp'
                    description: When the link expires, five minutes after it was created.
                required:
                  - id
                  - url
                  - status
                  - expires_at
        default:
          description: Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerFailure'
      security: []
components:
  schemas:
    LinkStatus:
      oneOf:
        - description: The user has not approved yet.
          type: string
          const: waiting
        - description: The user approved. `permit` holds their permit.
          type: string
          const: approved
        - description: Five minutes passed without approval. Create a new link.
          type: string
          const: expired
    Timestamp:
      type: string
      format: date-time
    PartnerFailure:
      description: >-
        A failed call. Handle it by HTTP status and `code`, and show `error` to
        the user.
      type: object
      properties:
        error:
          description: A message you can show the user.
          type: string
        code:
          description: >-
            A stable code such as `BAD_REQUEST`, `NOT_FOUND`, `CONFLICT` or
            `UNAUTHORIZED`. New codes can appear.
          type: string
      required:
        - error
        - code

````

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