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

# License Lookup

> Fetch raw license details without triggering validation side effects using GET /api/v1/license/:key.

Retrieve the full details of a license by its key. Unlike [`POST /api/v1/validate`](/api-reference/validate), this endpoint is read-only and has no side effects.

<Tip>
  Use the interactive playground on this page to test a lookup request with your product API key and a real license key.
</Tip>

## Endpoint

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET https://api.keyport.sbs/api/v1/license/:key
```

Replace `:key` with the license key you want to look up (e.g. `ABCD-EFGH-IJKL-MNOP`).

## Headers

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
Authorization: Bearer kp_live_xxxxxxxxxxxxxxxxxxxxxxxxx
```

## Behavior

This endpoint does **not**:

* register an IP address
* run validate-time business logic
* change license state in any way

Use it when you need to inspect license metadata — expiry, IP counts, version pins, customer info — without affecting the license.

<Note>
  This endpoint requires the same product API key in the `Authorization` header as the validate endpoint.
</Note>

## Response fields

<ResponseField name="id" type="string">
  Unique identifier for the license record.
</ResponseField>

<ResponseField name="organization_id" type="string">
  ID of the organization that owns this license.
</ResponseField>

<ResponseField name="product_id" type="string">
  ID of the product this license belongs to.
</ResponseField>

<ResponseField name="global_customer_id" type="string | null">
  ID of the customer this license is assigned to, if any.
</ResponseField>

<ResponseField name="license_key" type="string">
  The license key string itself.
</ResponseField>

<ResponseField name="status" type="string">
  Current status of the license (e.g. `active`, `revoked`, `expired`).
</ResponseField>

<ResponseField name="expires_at" type="string | null">
  ISO 8601 expiry timestamp. `null` for lifetime licenses.
</ResponseField>

<ResponseField name="is_lifetime" type="boolean">
  `true` if the license never expires.
</ResponseField>

<ResponseField name="ip_system_enabled" type="boolean">
  Whether IP-based access control is active for this license.
</ResponseField>

<ResponseField name="max_ips" type="number | null">
  Maximum number of unique IPs allowed. `null` if the IP system is disabled.
</ResponseField>

<ResponseField name="current_unique_ip_count" type="number">
  Number of unique IPs that have validated with this license so far.
</ResponseField>

<ResponseField name="notes" type="string | null">
  Optional notes attached to the license by your team. `null` if none were set.
</ResponseField>

<ResponseField name="version_pin_mode" type="string | null">
  The version enforcement mode in use (e.g. pinned, range). `null` if the version module is disabled.
</ResponseField>

<ResponseField name="version_pinned" type="string | null">
  The exact version pinned to this license, when applicable.
</ResponseField>

<ResponseField name="version_range_min" type="string | null">
  Minimum allowed version when a range is configured.
</ResponseField>

<ResponseField name="version_range_max" type="string | null">
  Maximum allowed version when a range is configured.
</ResponseField>

<ResponseField name="revoked_at" type="string | null">
  ISO 8601 timestamp of when the license was revoked. `null` if it has not been revoked.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when the license was created.
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 timestamp of the most recent update to the license record.
</ResponseField>

<ResponseField name="customer_email" type="string | null">
  Email address of the assigned customer.
</ResponseField>

<ResponseField name="customer_name" type="string | null">
  Display name of the assigned customer.
</ResponseField>

<ResponseField name="customer_discord_id" type="string | null">
  Discord user ID of the assigned customer, if provided.
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request GET \
    --url https://api.keyport.sbs/api/v1/license/ABCD-EFGH-IJKL-MNOP \
    --header 'Authorization: Bearer kp_live_xxxxxxxxxxxxxxxxxxxxxxxxx'
  ```

  ```json Response theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "id": "license_uuid",
    "organization_id": "org_uuid",
    "product_id": "product_uuid",
    "global_customer_id": "customer_uuid",
    "license_key": "ABCD-EFGH-IJKL-MNOP",
    "status": "active",
    "expires_at": null,
    "is_lifetime": true,
    "ip_system_enabled": true,
    "max_ips": 1,
    "current_unique_ip_count": 1,
    "notes": null,
    "version_pin_mode": null,
    "version_pinned": null,
    "version_range_min": null,
    "version_range_max": null,
    "revoked_at": null,
    "created_at": "2026-04-07T00:00:00.000Z",
    "updated_at": "2026-04-07T00:00:00.000Z",
    "customer_email": "customer@example.com",
    "customer_name": "Example Customer",
    "customer_discord_id": null
  }
  ```
</CodeGroup>


## OpenAPI

````yaml GET /api/v1/license/{key}
openapi: 3.0.3
info:
  title: KeyPort Public API
  version: v1
  description: Public license validation and license lookup endpoints for KeyPort.
servers:
  - url: https://api.keyport.sbs
    description: Production API
security:
  - bearerAuth: []
paths:
  /api/v1/license/{key}:
    get:
      summary: Look up a license by key
      operationId: getLicenseByKey
      parameters:
        - name: key
          in: path
          required: true
          schema:
            type: string
            example: ABCD-EFGH-IJKL-MNOP
      responses:
        '200':
          description: License details returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LicenseLookupResponse'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: License not found for this product.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
components:
  schemas:
    LicenseLookupResponse:
      type: object
      properties:
        id:
          type: string
          example: license_uuid
        organization_id:
          type: string
          example: org_uuid
        product_id:
          type: string
          example: product_uuid
        global_customer_id:
          type: string
          nullable: true
          example: customer_uuid
        license_key:
          type: string
          example: ABCD-EFGH-IJKL-MNOP
        status:
          type: string
          example: active
        expires_at:
          type: string
          format: date-time
          nullable: true
          example: null
        is_lifetime:
          type: boolean
          example: true
        ip_system_enabled:
          type: boolean
          example: true
        max_ips:
          type: integer
          nullable: true
          example: 1
        current_unique_ip_count:
          type: integer
          example: 1
        notes:
          type: string
          nullable: true
          example: null
        version_pin_mode:
          type: string
          nullable: true
          example: null
        version_pinned:
          type: string
          nullable: true
          example: null
        version_range_min:
          type: string
          nullable: true
          example: null
        version_range_max:
          type: string
          nullable: true
          example: null
        revoked_at:
          type: string
          format: date-time
          nullable: true
          example: null
        created_at:
          type: string
          format: date-time
          example: '2026-04-07T00:00:00.000Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-04-07T00:00:00.000Z'
        customer_email:
          type: string
          nullable: true
          example: customer@example.com
        customer_name:
          type: string
          nullable: true
          example: Example Customer
        customer_discord_id:
          type: string
          nullable: true
          example: null
    UnauthorizedError:
      type: object
      properties:
        valid:
          type: boolean
          example: false
        status:
          type: string
          example: invalid_api_key
        message:
          type: string
          example: >-
            Missing Authorization header. Use: Authorization: Bearer
            YOUR_API_KEY
    NotFoundError:
      type: object
      properties:
        message:
          type: string
          example: License not found.
        error:
          type: string
          example: Not Found
        statusCode:
          type: integer
          example: 404
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: Use your product API key in the Authorization header.

````