Sellfy Licenses API

openapi: 3.2.0
info:
  title: Documentation Licenses API
  version: 1.2.0
  description: '# Introduction


    Programmatic access to your Sellfy store from your own software.

    Endpoints are meant to be called from your server or application,

    and new ones are added regularly.


    # Authentication


    Every request is authenticated with an API token — a secret tied to

    your Sellfy account, so a request only ever sees your own data.


    To get a token:


    1. In the Sellfy dashboard, open **Store → Integrations → API keys**.

    2. Create a token and copy it right away — the full value is shown

    only once, on creation.

    3. Send it with every request in the `Authorization` header:


    ```

    Authorization: Bearer

    ```


    Requests without a valid token are answered with `401` and a `code`

    of `token_missing` or `token_invalid`. A token can be deleted in the

    dashboard at any time to cut an integration off.'
servers:
- url: https://api.sellfy.com
security:
- apiToken: []
tags:
- name: Licenses
  description: Validate, activate and revoke license keys sold with Sellfy products. A key is located by its `product_id` and `license_key` pair within your account.
  x-order: 2
paths:
  /v1/licenses/validate/:
    get:
      tags:
      - Licenses
      operationId: validate-license
      summary: Validate a license key
      description: 'Looks up the current state of a license key. Read-only — validating

        never changes the key.'
      parameters:
      - name: product_id
        in: query
        required: true
        description: 'ID of the Sellfy product the license key belongs to. To find it, open **Products → All products** in your dashboard and pick **Copy product ID** from the options menu (⋯) of the product row. Alternatively, open the product for editing and copy the ID from the address bar: it is the last part of the URL'
        schema:
          title: Product Id
          type: string
      - name: license_key
        in: query
        required: true
        description: The license key string.
        schema:
          minLength: 1
          title: License Key
          type: string
      responses:
        '200':
          description: Current state of the license key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LicenseStateResponse'
        '400':
          description: The request is missing or has invalid parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: 'The API token is missing or invalid (`code`: `token_missing` or `token_invalid`).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 'No license key of yours matches `product_id` and `license_key` (`code`: `not_found`).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'Too many failed lookups from this IP (`code`: `too_many_attempts`). More than 30 lookups of non-existent keys block further requests for 15 minutes; successful lookups are never throttled.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/licenses/activations/:
    post:
      tags:
      - Licenses
      operationId: activate-license
      summary: Activate a license key
      description: 'Records an activation on the key and returns just that activation.

        Store its `id` — deactivating later is

        `DELETE /v1/licenses/activations/{activation_id}/`.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LicenseActivateInput'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/LicenseActivateInput'
      responses:
        '200':
          description: A single activation recorded on the license key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LicenseActivationResponse'
        '400':
          description: The request is missing or has invalid parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: 'The API token is missing or invalid (`code`: `token_missing` or `token_invalid`).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 'The key exists but is not valid (`code`: `revoked` or `expired`).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 'No license key of yours matches `product_id` and `license_key` (`code`: `not_found`).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'Too many failed lookups from this IP (`code`: `too_many_attempts`). More than 30 lookups of non-existent keys block further requests for 15 minutes; successful lookups are never throttled.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/licenses/activations/{activation_id}/:
    delete:
      tags:
      - Licenses
      operationId: deactivate-license
      summary: Deactivate a license key activation
      description: 'Releases an activation recorded earlier, e.g. when the buyer moves the

        license to another device, and returns the key''s remaining state. The

        activation `id` alone addresses it — activation ids are unique within

        your account.'
      parameters:
      - name: activation_id
        in: path
        required: true
        description: Id of the activation to release, as returned when activating.
        schema:
          type: string
      responses:
        '200':
          description: Current state of the license key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LicenseStateResponse'
        '401':
          description: 'The API token is missing or invalid (`code`: `token_missing` or `token_invalid`).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 'No activation of yours has this id (`code`: `activation_not_found`).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/licenses/revoke/:
    post:
      tags:
      - Licenses
      operationId: revoke-license
      summary: Revoke a license key
      description: 'Marks the key as revoked so it can no longer be activated — the same

        action as revoking the key in the Sellfy dashboard, where it can also

        be reactivated. Idempotent — revoking an already-revoked key just

        returns its state.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LicenseLookupInput'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/LicenseLookupInput'
      responses:
        '200':
          description: Current state of the license key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LicenseStateResponse'
              example:
                valid: false
                status: revoked
                activations: []
        '400':
          description: The request is missing or has invalid parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: 'The API token is missing or invalid (`code`: `token_missing` or `token_invalid`).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 'No license key of yours matches `product_id` and `license_key` (`code`: `not_found`).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'Too many failed lookups from this IP (`code`: `too_many_attempts`). More than 30 lookups of non-existent keys block further requests for 15 minutes; successful lookups are never throttled.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    LicenseActivationResponse:
      description: A single activation recorded on the license key.
      properties:
        id:
          description: Id of the activation — deactivate it with `DELETE /v1/licenses/activations/{activation_id}/`.
          title: Id
          type: string
        activated_at:
          title: Activated At
          type: string
        meta:
          description: The `meta` data sent when activating.
          readOnly: true
          title: Meta
          type: object
      required:
      - id
      - activated_at
      - meta
      title: LicenseActivationResponse
      type: object
    Error:
      type: object
      description: Error envelope with a machine-readable reason code.
      properties:
        code:
          type: string
      required:
      - code
    LicenseActivateInput:
      properties:
        product_id:
          description: 'ID of the Sellfy product the license key belongs to. To find it, open **Products → All products** in your dashboard and pick **Copy product ID** from the options menu (⋯) of the product row. Alternatively, open the product for editing and copy the ID from the address bar: it is the last part of the URL'
          title: Product Id
          type: string
        license_key:
          description: The license key string.
          minLength: 1
          title: License Key
          type: string
        meta:
          default: {}
          description: Free-form data describing the activation (e.g. device id, site url). Stored as-is and returned with the activation.
          title: Meta
          type: object
      required:
      - product_id
      - license_key
      title: LicenseActivateInput
      type: object
    LicenseLookupInput:
      properties:
        product_id:
          description: 'ID of the Sellfy product the license key belongs to. To find it, open **Products → All products** in your dashboard and pick **Copy product ID** from the options menu (⋯) of the product row. Alternatively, open the product for editing and copy the ID from the address bar: it is the last part of the URL'
          title: Product Id
          type: string
        license_key:
          description: The license key string.
          minLength: 1
          title: License Key
          type: string
      required:
      - product_id
      - license_key
      title: LicenseLookupInput
      type: object
    LicenseStateResponse:
      description: Current state of the license key.
      properties:
        valid:
          description: Whether the key is currently usable.
          readOnly: true
          title: Valid
          type: boolean
        status:
          description: '`issued` (sold, not activated yet), `activated` (has at least one activation), or the reason the key is not valid: `revoked` or `expired`.'
          readOnly: true
          title: Status
          type: string
        activations:
          description: Currently active activations, oldest first.
          items:
            $ref: '#/components/schemas/LicenseActivationResponse'
          readOnly: true
          title: Activations
          type: array
      required:
      - valid
      - status
      - activations
      title: LicenseStateResponse
      type: object
    ValidationError:
      type: object
      description: Request validation failure.
      properties:
        error:
          type: string
          description: Message of the first validation error.
        errors:
          type: array
          items:
            type: object
            properties:
              label:
                type: string
                description: Dotted path of the invalid field.
              message:
                type: string
  securitySchemes:
    apiToken:
      type: http
      scheme: bearer
      description: API token created in the Sellfy dashboard. The full value is shown only once, on creation.