menu

linkAPI Reference

The Keygen API is organized around REST principles. All requests must be made over TLS/SSL. In addition, all request and response bodies, including errors, are encoded in JSON format.

The API has predictable, resource-oriented URLs, and uses standard HTTP response codes to indicate API errors. We use built-in HTTP features, like authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from any client-facing software application.

linkClient Libraries

At the moment we're focused on our HTTP API endpoints. As time goes by we'll be featuring here some more of our open-source clients for different languages and frameworks, as well as those contributed by the community.

If you have written one yourself, please let us know!.

We will collaborate with project maintainers to keep open source libraries up-to-date as our systems evolve. If you would like us to add documentation examples for a specific language, or if you would like us to add an open-source library you created, please email [email protected].

linkPre-populated Examples

Your authentication token is pre-populated in all the examples on this page if you're currently logged in to your dashboard, so you can test any example right away. Only you can see these values.

The pre-populated token is an admin token and is not meant to be used in client-facing code, stored in version control, and so forth.

linkArchitecture

How to model the communication layer between your app and Keygen.

A) Direct

First up is the direct approach, utilizing a direct communication channel from your app to Keygen's API. This allows users to for example create licenses from within your app, while your server responds to webhook events accordingly, updating records to reflect any changes made server-side as well as to handle invoicing your users for any purchased licenses.

Using the direct architecture also lightens the load on your servers, allowing user's to interact directly with Keygen's APIs for most of their transactions, e.g. license validation and creation, as well as managing their machines. You can then respond to the appropriate webhook events to for example charge a customer for a new license.

On the topic of billing, it is recommended that your users register through your server, so that you can handle the initial collection of user billing information. We recommend using Stripe for billing. After you've created a user account, you can attach their Stripe customer_id to the user's metadata attribute.

If you'd like to allow registration directly from your app, you will need to collect a Stripe token and attach that as metadata, so that your server can respond to Keygen's user.created webhook event and finish the billing process. If your app is free to use, then registration is as simple as creating a new user.

Do not attach sensitive information directly to your users using the metadata attribute. Doing so is a violation of our terms of use. If you're using Stripe, you need only attach their Stripe customer_id, or a secure representation of a card (such as a stripe_token), which can then be used to look up their information server-side when required.

B) Middleman

Next is an alternate approach, using your server as a middleman for communication between your app and Keygen's API. This architecture allows you to more easily manage and validate events, instead of relying solely on listening for webhook events.

In addition, this approach also allows you to store user accounts within your own database, instead of utilizing Keygen's user-management features. You may do so by associating the unique id of a user-less license to a user model within your database.

Did you know that you can create a license without a user? You can do so by going through the usual license creation flow, while ommiting the user relationship. This can be used to create licenses for users stored within your own database.

linkVersioning

When we introduce breaking changes to the API, we will release a new numbered version, e.g. we will go from v1 to v2. The current version is v1. All changes will be detailed within our changelog.

linkAPI Stability

We will not introduce breaking changes into the API without bumping the current version. You can rest assured that the endpoints you're utilizing within your product are stable.

Keep in mind that stable does not mean complete. We could potentially add new resources and actions, but existing resources will remain unchanged.

linkErrors

Our API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a validation failed, etc.), and codes in the 5xx range indicate an error with our servers (these are rare).

linkAttributes

  • linktitle

    string

    A short, human-readable summary of the problem.

  • linkdetail

    string

    A more detailed human-readable explanation of the problem.

  • linksource

    hash

    An object containing references to the source of the error.

  • linksource.pointer

    string

    A pointer to the problem data, e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute.

Example error

{
  "errors": [
    {
      "title": "Unprocessable entity",
      "detail": "must be a valid email",
      "source": {
        "pointer": "/data/attributes/email"
      }
    },
    …
  ]
}

linkError Codes

Code Meaning
200 OK Everything worked as expected.
201 Created The resource was created successfully.
202 Accepted The request has been accepted for processing.
204 No content Everything worked as expected, but there was nothing to respond with.
400 Bad Request The request was unacceptable, often due to missing or unpermitted parameters.
401 Unauthorized No valid API token provided.
403 Forbidden The authenticated entity does not have permission to complete the request.
404 Not Found The requested resource doesn't exist.
409 Conflict The request could not be completed because the resource already exists.
422 Unprocessable A validation error occurred on the resource.
429 Too Many Requests Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
5xx Server Errors Something went wrong on our end. (These are rare.)

linkAuthentication

Requests are authenticated using a bearer token in an Authorization header. If you're using one of our language bindings, then this will be handled for you automatically with each request, if a session has been created.

Your authentication token is pre-populated in all the examples on this page if you're currently logged in to your dashboard, so you can test any example right away. Only you can see these values. The pre-populated token is an admin token and is not meant to be used in client-facing code, stored in version control, and so forth.

You can manage your tokens using the Tokens resource. Along with users, a product can also authenticate using product tokens; to create a new product token, please see the Product token relationship. All user tokens have a 2 week expiry and can be regenerated as needed during that timeframe. Admin and product tokens do not expire, and should only be used server-side.

Most API endpoints will require authentication, and access to resources depends on the token bearer's authorization and role.

Tokens should be treated as passwords. Different tokens carry different privileges depending on the bearer of the token, so be sure to keep them secret! Do not share your secret API tokens in publicly accessible areas such as GitHub, client-facing code, and so forth. If in doubt, please reset or revoke the offending authentication token(s).

linkAuthorization

Access to certain resources is dependent upon a token bearer's role. Most of the time you will be authenticating as one of your users, which will allow access to a small subset of resources available to your account. In other cases, as when you are using the middleman architecture, you may be authenticating as a product, or even an admin; in these cases, you will have access to a wider range of resources.

Resource attributes and relationships marked with a "protected" badge are only allowed to be specified if the authenticated bearer is an admin of the account, or a product that owns the specified resource. Attributes and relationships marked with a "read only" badge can not be modified.

Many resource endpoints are automatically scoped according to the token bearer's role. For example, listing all licenses while authenticated as a product will only list licenses associated with that particular product. Attempting to access resources that the bearer does not have access to will respond with a 403 forbidden error.

Never hard-code authentication tokens within your client-facing product – doing so could leave your product open to major exploitations by allowing a malicious user the ability to fully manage your account's resources. The only time you should be using your admin or product token(s) directly is if you are working with Keygen server-side.

linkRate Limiting

A single IP address can make a maximum of 100 requests per 10 second window, regardless of authentication. If we see patterns of abuse, this may be lowered or the IP may be temporarily blacklisted or in rare cases of significant abuse, permanently blacklisted.

You can check the returned HTTP headers of any API request to see your current rate limit status:

Header Description
X-RateLimit-Limit The maximum number of requests that the IP is permitted to make per 10 second window.
X-RateLimit-Remaining The number of requests remaining in the current rate limit window.
X-RateLimit-Reset The time at which the current rate limit window resets in UTC epoch seconds.
Need a higher limit? Give us a shout, as you may be a good candidate for an on-premise instance of Keygen.

Example error

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 71
X-RateLimit-Reset: 1490973281
{
  "errors": [
    {
      "title": "Throttle limit reached",
      "detail": "Throttle limit has been reached for your IP address."
    }
  ]
}

linkMetadata

Many resources including products, users, licenses, machines and policies have a metadata attribute. You can use this attribute to attach key-value data to the given resource.

Metadata is useful for storing additional, structured information on an object. As an example, you could store your user's zipcode, their id within your own database (if applicable), or their Stripe customer_id for billing purposes.

Since the metadata attribute is simply a key-value store (hash), all write operations will overwrite the entire hash, so be sure to merge existing data on your end when performing updates.

Do not attach sensitive billing information directly to your users using the metadata attribute. Doing so is a violation of our terms of use. If you're using Stripe, you need only attach their Stripe customer_id, or a temporary secure representation of a card (such as a stripe_token), which can then be used to look up their information server-side when required.

linkPagination

All top-level API resources have support for bulk fetches via "list" API methods. For instance you can list users, list licenses, and list machines. These list API methods share a common format, taking an optional page query parameter.

Our API utilizes a page-based strategy via the page[size] and page[number] parameters. All results are returned in reverse chronological order.

linkParameters

  • linkpage

    hash

    Hash containing page size and page number.

  • linkpage.size

    integer

    The page size. Must be a number between 1 and 100.

  • linkpage.number

    integer

    The page number.

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/users?page[size]=25&page[number]=2", {
  method: "GET",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})

const { data, links, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/users?page[size]=25&page[number]=2",
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl https://api.keygen.sh/v1/accounts/<%= account %>/users?page[size]=25&page[number]=2 -g \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response

{
  "data": [
    {
      "id": "6ed498fe-5f5f-49af-82ee-cb7400cc4522",
      "type": "users",
      "links": {
        "self": "/v1/accounts/<%= account %>/users/6ed498fe-5f5f-49af-82ee-cb7400cc4522"
      },
      "attributes": {
        "fullName": "Marty McFly",
        "firstName": "Marty",
        "lastName": "McFly",
        "email": "[email protected]",
        "role": "user",
        "metadata": {},
        "created": "2017-01-02T19:48:50.077Z",
        "updated": "2017-01-02T19:48:50.077Z"
      },
      "relationships": {
        "account": {
          "links": {
            "related": "/v1/accounts/<%= account %>"
          },
          "data": {
            "type": "accounts",
            "id": "<%= account %>"
          }
        },
        "products": {
          "links": {
            "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/products"
          }
        },
        "licenses": {
          "links": {
            "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/licenses"
          }
        },
        "machines": {
          "links": {
            "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/machines"
          }
        },
        "tokens": {
          "links": {
            "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/tokens"
          }
        }
      }
    },
    …
  ],
  "links": {
    "self": "/v1/accounts/<%= account %>/users?page[size]=25&page[number]=2",
    "prev": "/v1/accounts/<%= account %>/users?page[size]=25&page[number]=1",
    "next": "/v1/accounts/<%= account %>/users?page[size]=25&page[number]=3",
    "first": "/v1/accounts/<%= account %>/users?page[size]=25&page[number]=1",
    "last": "/v1/accounts/<%= account %>/users?page[size]=25&page[number]=4"
  }
}

linkIdempotency

Some resources, such as webhook events may contain an idempotency token inside of a meta hash. In the case of webhook events, these tokens allow you to safely retry events without accidentally responding to the same event multiple times.

linkExample scenario

When a user creates a new license, you would want to make sure that the license.created webhook event that you're listening for would only be acted upon once, regardless of how many times you retry the event, to guarantee you only charge your user for a single license.

You can accomplish this by logging the idempotency token (to a database, for example) and ignoring future webhook events that come through with an identical token, signaling a retried event.

Although retrying a webhook event creates a new resource, the idempotency token will stay the same throughout the event's lifetime.

Example resource

A failed webhook event resource.

{
  "data": {
    "id": "2bc99fe1-f315-4877-ac5f-542240c4e883",
    "type": "webhook-events",
    "meta": {
      "idempotencyToken": "e8e0fbb598e8bcfd0e94ceb79199edc79e6ab53f4a4bbb32d7aede7964e7c3v1",
    },
    "links": {
      "self": "/v1/accounts/<%= account %>/webhook-events/2bc99fe1-f315-4877-ac5f-542240c4e883"
    },
    "attributes": {
      "endpoint": "https://example.com/webhooks",
      "payload": "{\"data\":{…}}",
      "event": "license.created",
      "status": "failed",
      "created": "2017-01-02T20:26:53.464Z",
      "updated": "2017-01-02T20:26:53.464Z"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      }
    }
  }
}

Example request

Retry the above failed webhook event resource.

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/webhook-events/2bc99fe1-f315-4877-ac5f-542240c4e883/actions/retry", {
  method: "POST",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/webhook-events/2bc99fe1-f315-4877-ac5f-542240c4e883/actions/retry",
  method: .post,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl -X POST https://api.keygen.sh/v1/accounts/<%= account %>/webhook-events/2bc99fe1-f315-4877-ac5f-542240c4e883/actions/retry \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response

Notice that it's a new resource, yet the idempotency token matches the original event.

{
  "data": {
    "id": "1bda5fd5-6d82-49f5-b5b8-71bb432a32bb",
    "type": "webhook-events",
    "meta": {
      "idempotencyToken": "e8e0fbb598e8bcfd0e94ceb79199edc79e6ab53f4a4bbb32d7aede7964e7c3v1",
    },
    "links": {
      "self": "/v1/accounts/<%= account %>/webhook-events/1bda5fd5-6d82-49f5-b5b8-71bb432a32bb"
    },
    "attributes": {
      "endpoint": "https://example.com/webhooks",
      "payload": "{\"data\":{…}}",
      "event": "license.created",
      "status": "queued",
      "created": "<%= created %>",
      "updated": "<%= updated %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      }
    }
  }
}

linkTokens

linkThe token object

Below you will find the various attributes for the token resource, as well as the token resource's relationships. The actual token string is hashed before being stored in our databases, thus is only available directly after generating/regenerating a token.

linkAttributes

  • linktoken

    stringread only

    The raw token of the token. This attribute is only available to read directly after token generation.

  • linkexpiry

    timestampread only

    When the token expires.

  • linkcreated

    timestampread only

    When the token was created.

  • linkupdated

    timestampread only

    When the token was last updated.

linkRelationships

  • linkaccount

    individual

    The account that the token belongs to.

  • linkbearer

    individual

    The bearer of the token.

Example object

{
  "data": {
    "id": "6a7562be-b302-43d2-a550-30d6026247aa",
    "type": "tokens",
    "attributes": {
      "token": "9bc31b8d19a94d82a15742678d8f2540.6a7562beb30243d2a55030d6026247aa.edc19321739951dc8fe9ce7d27c703a74faabd7dee8228b8ad4ec6e69692d6959449d9694fd93eca48b33f023bd1319f14b90de1cba5001945dea6b66f5986v1",
      "expiry": "<%= expiry %>",
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "bearer": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298"
        },
        "data": {
          "type": "users",
          "id": "a5a154d2-f026-40fa-bc8d-a7e3ca415298"
        }
      }
    }
  }
}

linkGenerate a token

Generate a new token resource for a user. To generate a token for a product, see the product token relationship.

Admin and product tokens should not be included in any client-facing code, as they offer full access to all of your account's resources. You should always authenticate as one of your users within your product. Admin and product tokens should only be used server-side.

linkAuthentication

  • linkBasic

    required

    The email and password of the user.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

Definition

POST https://api.keygen.sh/v1/accounts/<%= account %>/tokens \
  -u "{CREDENTIALS}"

Example request

const fetch = require("node-fetch")

const credentials = new Buffer("<%= email %>:<%= password %>").toString("base64")
const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/tokens", {
  method: "POST",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": `Basic ${credentials}`
  }
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

let credentials = Data("<%= email %>:<%= password %>".utf8).base64EncodedString()

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/tokens",
  method: .post,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Basic \(credentials)"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl -X POST https://api.keygen.sh/v1/accounts/<%= account %>/tokens \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -u "<%= email %>:<%= password %>"

Example response / 201 Created

{
  "data": {
    "id": "6a7562be-b302-43d2-a550-30d6026247aa",
    "type": "tokens",
    "attributes": {
      "token": "9bc31b8d19a94d82a15742678d8f2540.6a7562beb30243d2a55030d6026247aa.edc19321739951dc8fe9ce7d27c703a74faabd7dee8228b8ad4ec6e69692d6959449d9694fd93eca48b33f023bd1319f14b90de1cba5001945dea6b66f598dv1",
      "expiry": "<%= expiry %>",
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "bearer": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298"
        },
        "data": {
          "type": "users",
          "id": "a5a154d2-f026-40fa-bc8d-a7e3ca415298"
        }
      }
    }
  }
}

linkRetrieve a token

Retrieves the details of an existing token.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to view the resource: either an admin or the token owner.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

  • linkid

    string, required

    The identifier of the token to be retrieved.

Definition

GET https://api.keygen.sh/v1/accounts/<%= account %>/tokens/{ID}

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/tokens/6a7562be-b302-43d2-a550-30d6026247aa", {
  method: "GET",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/tokens/6a7562be-b302-43d2-a550-30d6026247aa",
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl https://api.keygen.sh/v1/accounts/<%= account %>/tokens/6a7562be-b302-43d2-a550-30d6026247aa \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": {
    "id": "6a7562be-b302-43d2-a550-30d6026247aa",
    "type": "tokens",
    "attributes": {
      "expiry": "<%= expiry %>",
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "bearer": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298"
        },
        "data": {
          "type": "users",
          "id": "a5a154d2-f026-40fa-bc8d-a7e3ca415298"
        }
      }
    }
  }
}

linkRegenerate a token

Regenerate an existing token resource. This will replace the token attribute with a new secure token, and extend the expiry by 2 weeks.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to manage the resource: either an admin or the token owner.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

  • linkid

    string, optional

    The identifier of the token to be regenerated. If ommited, the token used to authenticate will be regenerated.

Definition

PUT https://api.keygen.sh/v1/accounts/<%= account %>/tokens/{ID}

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/tokens/6a7562be-b302-43d2-a550-30d6026247aa", {
  method: "PUT",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/tokens/6a7562be-b302-43d2-a550-30d6026247aa",
  method: .put,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl -X PUT https://api.keygen.sh/v1/accounts/<%= account %>/tokens/6a7562be-b302-43d2-a550-30d6026247aa \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": {
    "id": "6a7562be-b302-43d2-a550-30d6026247aa",
    "type": "tokens",
    "attributes": {
      "token": "9bc31b8d19a94d82a15742678d8f2540.6a7562beb30243d2a55030d6026247aa.0e00ffa203dcc6871c010c7d85ce13556c7ff70abcc0df4287b40dab8ade4a5fc4d4eb7bf1ccdef2dc892ad21bb57c451191c3061296c417eaf590d6ae640bv1",
      "expiry": "<%= expiry %>",
      "created": "<%= created %>",
      "updated": "<%= updated %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "bearer": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298"
        },
        "data": {
          "type": "users",
          "id": "a5a154d2-f026-40fa-bc8d-a7e3ca415298"
        }
      }
    }
  }
}

linkRevoke a token

Permanently revokes a token. It cannot be undone. This action also immediately invalidates all sessions using the given token.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to manage the resource: either an admin or the token owner.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

  • linkid

    string, required

    The identifier of the token to be revoked.

Definition

DELETE https://api.keygen.sh/v1/accounts/<%= account %>/tokens/{ID}

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/tokens/6a7562be-b302-43d2-a550-30d6026247aa", {
  method: "DELETE",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/tokens/6a7562be-b302-43d2-a550-30d6026247aa",
  method: .delete,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let status = response.response?.statusCode
}
curl -X DELETE https://api.keygen.sh/v1/accounts/<%= account %>/tokens/6a7562be-b302-43d2-a550-30d6026247aa \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 204 No Content

No content

linkList all tokens

Returns a list of tokens. The tokens are returned sorted by creation date, with the most recent tokens appearing first. Resources are automatically scoped to the authenticated bearer e.g. when authenticated as a product, only tokens that belong to the specific product will be listed.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to view the resources.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

linkFilters

  • linklimit

    integer, default is10

    A limit on the number of users to be returned. Limit must be a number between 1 and 100.

    https://api.keygen.sh/v1/accounts/<%= account %>/tokens?limit=25

  • linkpage

    hash

    Hash containing page size and page number. Page size must be a number between 1 and 100

    https://api.keygen.sh/v1/accounts/<%= account %>/tokens?page[size]=15&page[number]=2

Definition

GET https://api.keygen.sh/v1/accounts/<%= account %>/tokens{FILTERS}

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/tokens?limit=15", {
  method: "GET",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/tokens?limit=15",
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl https://api.keygen.sh/v1/accounts/<%= account %>/tokens?limit=15 -g \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": [
    {
      "id": "6a7562be-b302-43d2-a550-30d6026247aa",
      "type": "tokens",
      "attributes": {
        "expiry": "<%= expiry %>",
        "created": "<%= created %>",
        "updated": "<%= created %>"
      },
      "relationships": {
        "account": {
          "links": {
            "related": "/v1/accounts/<%= account %>"
          },
          "data": {
            "type": "accounts",
            "id": "<%= account %>"
          }
        },
        "bearer": {
          "links": {
            "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298"
          },
          "data": {
            "type": "users",
            "id": "a5a154d2-f026-40fa-bc8d-a7e3ca415298"
          }
        }
      }
    },
    …
  ]
}

linkPlans

linkThe plan object

Below you will find the various attributes for the plan resource. These are the paid Keygen plans available for subscription.

linkAttributes

  • linkname

    stringread only

    The name of the plan.

  • linkprice

    integerread only

    The price of the plan in cents.

  • linktrialDuration

    integerread only

    The duration of the plan's trial period in seconds.

  • linkmaxUsers

    integerread only

    The maximum amount of users the plan allows.

  • linkmaxPolicies

    integerread only

    The maximum amount of policies the plan allows.

  • linkmaxLicenses

    integerread only

    The maximum amount of licenses the plan allows.

  • linkmaxProducts

    integerread only

    The maximum amount of products the plan allows.

  • linkcreated

    timestampread only

    When the plan was created.

  • linkupdated

    timestampread only

    When the plan was last updated.

Example object

{
  "data": {
    "id": "0e040820-aba5-4e0e-8947-b9f7cf76e484",
    "type": "plans",
    "links": {
      "self": "/v1/plans/0e040820-aba5-4e0e-8947-b9f7cf76e484"
    },
    "attributes": {
      "name": "Enterprise",
      "price": 24900,
      "trialDuration": 604800,
      "maxUsers": null,
      "maxPolicies": null,
      "maxLicenses": null,
      "maxProducts": 5,
      "created": "<%= created %>",
      "updated": "<%= created %>"
    }
  }
}

linkRetrieve a plan

Retrieves the details of an existing plan.

linkAuthentication

linkParameters

  • linkid

    string, required

    The identifier of the plan to be retrieved.

Definition

GET https://api.keygen.sh/v1/plans/{ID}

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/plans/0e040820-aba5-4e0e-8947-b9f7cf76e484", {
  method: "GET",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json"
  }
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/plans/0e040820-aba5-4e0e-8947-b9f7cf76e484",
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl https://api.keygen.sh/v1/plans/0e040820-aba5-4e0e-8947-b9f7cf76e484 \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json'

Example response / 200 OK

{
  "data": {
    "id": "0e040820-aba5-4e0e-8947-b9f7cf76e484",
    "type": "plans",
    "links": {
      "self": "/v1/plans/0e040820-aba5-4e0e-8947-b9f7cf76e484"
    },
    "attributes": {
      "name": "Enterprise",
      "price": 24900,
      "trialDuration": 604800,
      "maxUsers": null,
      "maxPolicies": null,
      "maxLicenses": null,
      "maxProducts": 5,
      "created": "<%= created %>",
      "updated": "<%= created %>"
    }
  }
}

linkList all plans

Returns a list of plans. The plans are returned sorted by creation date, with the most recent plans appearing first.

linkAuthentication

linkFilters

  • linklimit

    integer, default is10

    A limit on the number of plans to be returned. Limit must be a number between 1 and 100.

    https://api.keygen.sh/v1/plans?limit=25

  • linkpage

    hash

    Hash containing page size and page number. Page size must be a number between 1 and 100

    https://api.keygen.sh/v1/plans?page[size]=15&page[number]=2

Definition

GET https://api.keygen.sh/v1/plans{FILTERS}

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/plans?limit=15", {
  method: "GET",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json"
  }
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/plans?limit=15",
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl https://api.keygen.sh/v1/plans?limit=15 -g \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json'

Example response / 200 OK

{
  "data": [
    {
      "id": "0e040820-aba5-4e0e-8947-b9f7cf76e484",
      "type": "plans",
      "links": {
        "self": "/v1/plans/0e040820-aba5-4e0e-8947-b9f7cf76e484"
      },
      "attributes": {
        "name": "Enterprise",
        "price": 24900,
        "trialDuration": 604800,
        "maxUsers": null,
        "maxPolicies": null,
        "maxLicenses": null,
        "maxProducts": 5,
        "created": "<%= created %>",
        "updated": "<%= created %>"
      }
    },
    …
  ]
}

linkAccounts

linkThe account object

Below you will find the various attributes for the account resource, as well as the account resource's relationships.

linkAttributes

  • linkname

    string

    The name of the account.

  • linkslug

    string

    The unique slug of the account. This can be used in place of the account's unique identifier when making requests.

  • linkprotected

    boolean, default isfalse

    Whether or not the account is protected. A protected account disallows public user and license creation and management, useful in situations where Keygen is only managed server-side or when you aren't listening for the appropriate user-initiated webhook events.

  • linkcreated

    timestampread only

    When the account was created.

  • linkupdated

    timestampread only

    When the account was last updated.

linkRelationships

  • linkbilling

    individual

    The billing information for the account.

  • linkplan

    individual

    The plan that the account is subscribed to.

  • linkwebhook-endpoints

    collection

    Webhook endpoints for the account.

  • linkwebhook-events

    collection

    Webhook events for the account.

  • linkproducts

    collection

    Products for the account.

  • linkpolicies

    collection

    Policies for the account.

  • linkusers

    collection

    Users for the account.

  • linkkeys

    collection

    Keys for the account.

  • linklicenses

    collection

    Licenses for the account.

  • linkmachines

    collection

    Machines for the account.

  • linktokens

    collection

    Tokens for the account.

Example object

{
  "data": {
    "id": "fff33d8f-11b8-428d-a949-db2b74d7c2f2",
    "type": "accounts",
    "links": {
      "self": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2"
    },
    "attributes": {
      "name": "Tesla",
      "slug": "tesla",
      "protected": false,
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "billing": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/billing"
        },
        "data": {
          "type": "billings",
          "id": "00461c96-27c3-4c68-b180-e6b7bc13dfab"
        }
      },
      "plan": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/plan"
        },
        "data": {
          "type": "plans",
          "id": "ecd0aaa1-86e7-4f06-9f82-2985585c94a3"
        }
      },
      "webhook-endpoints": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/webhook-endpoints"
        }
      },
      "webhook-events": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/webhook-events"
        }
      },
      "products": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/products"
        }
      },
      "policies": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/policies"
        }
      },
      "users": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/users"
        }
      },
      "keys": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/keys"
        }
      },
      "licenses": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/licenses"
        }
      },
      "machines": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/machines"
        }
      },
      "tokens": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/tokens"
        }
      }
    }
  }
}

linkCreate an account

Creates a new account resource.

linkAuthentication

linkAttributes

  • linkname

    string, required

    The name of the account.

  • linkslug

    string, required

    The unique slug of the account.

  • linkprotected

    boolean, optional

    Whether or not the account is protected.

linkRelationships

  • linkplan

    hash, required

    The plan to subscribe the account to.

  • linkadmins

    array<hash>, required

    An array of founding admin users for the account.

  • linkadmin.firstName

    string, required

    The first name of the admin user.

  • linkadmin.lastName

    string, required

    The last name of the admin user.

  • linkadmin.email

    string, required

    The unique email of the admin user.

  • linkadmin.password

    string, required

    The password for the admin user.

Definition

POST https://api.keygen.sh/v1/accounts \
  -d '{ "data": { "type": "accounts", "attributes": {DATA}, "relationships": {DATA} } }'

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts", {
  method: "POST",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json"
  },
  body: JSON.stringify({
    "data": {
      "type": "accounts",
      "attributes": {
        "name": "Tesla",
        "slug": "tesla"
      },
      "relationships": {
        "plan": {
          "data": {
            "type": "plans",
            "id": "fdac2e37-183f-4e5d-8861-c88c34d4327d"
          }
        },
        "admins": {
          "data": [{
            "type": "users",
            "attributes": {
              "firstName": "Elon",
              "lastName" "Musk",
              "email": "[email protected]",
              "password": "$s4PeRh7rk9Ect9q^^RQL2jmMd{T%G"
            }
          }]
        }
      }
    }
  })
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts",
  method: .post,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json"
  ],
  parameters: [
    "data": [
      "type": "accounts",
      "attributes": [
        "name": "Tesla",
        "slug": "tesla"
      ],
      "relationships": [
        "plan": [
          "data": [
            "type": "plans",
            "id": "fdac2e37-183f-4e5d-8861-c88c34d4327d"
          ]
        ],
        "admins": [
          "data": [[
            "type": "users",
            "attributes": [
              "firstName": "Elon",
              "lastName" "Musk",
              "email": "[email protected]",
              "password": "$s4PeRh7rk9Ect9q^^RQL2jmMd{T%G"
            ]
          ]]
        ]
      ]
    ]
  ],
  encoding: JSONEncoding.default
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl -X POST https://api.keygen.sh/v1/accounts \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -d '{
        "data": {
          "type": "accounts",
          "attributes": {
            "name": "Tesla",
            "slug": "tesla"
          },
          "relationships": {
            "plan": {
              "data": {
                "type": "plans",
                "id": "fdac2e37-183f-4e5d-8861-c88c34d4327d"
              }
            },
            "admins": {
              "data": [{
                "type": "users",
                "attributes": {
                  "firstName": "Elon",
                  "lastName" "Musk",
                  "email": "[email protected]",
                  "password": "$s4PeRh7rk9Ect9q^^RQL2jmMd{T%G"
                }
              }]
            }
          }
        }
      }'

Example response / 201 Created

{
  "data": {
    "id": "fff33d8f-11b8-428d-a949-db2b74d7c2f2",
    "type": "accounts",
    "links": {
      "self": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2"
    },
    "attributes": {
      "name": "Tesla",
      "slug": "tesla",
      "protected": false,
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "billing": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/billing"
        },
        "data": {
          "type": "billings",
          "id": "00461c96-27c3-4c68-b180-e6b7bc13dfab"
        }
      },
      "plan": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/plan"
        },
        "data": {
          "type": "plans",
          "id": "ecd0aaa1-86e7-4f06-9f82-2985585c94a3"
        }
      },
      "webhook-endpoints": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/webhook-endpoints"
        }
      },
      "webhook-events": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/webhook-events"
        }
      },
      "products": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/products"
        }
      },
      "policies": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/policies"
        }
      },
      "users": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/users"
        }
      },
      "keys": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/keys"
        }
      },
      "licenses": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/licenses"
        }
      },
      "machines": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/machines"
        }
      },
      "tokens": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/tokens"
        }
      }
    }
  }
}

linkRetrieve an account

Retrieves the details of an existing account.

linkAuthentication

  • linkBearer

    required

    An authentication token with admin privileges.

linkParameters

  • linkid

    string, required

    The identifier or slug of the account to be retrieved.

Definition

GET https://api.keygen.sh/v1/accounts/{ID}

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2", {
  method: "GET",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2",
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl https://api.keygen.sh/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2 \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": {
    "id": "fff33d8f-11b8-428d-a949-db2b74d7c2f2",
    "type": "accounts",
    "links": {
      "self": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2"
    },
    "attributes": {
      "name": "Tesla",
      "slug": "tesla",
      "protected": false,
      "created": "<%= created %>",
      "updated": "<%= updated %>"
    },
    "relationships": {
      "billing": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/billing"
        },
        "data": {
          "type": "billings",
          "id": "00461c96-27c3-4c68-b180-e6b7bc13dfab"
        }
      },
      "plan": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/plan"
        },
        "data": {
          "type": "plans",
          "id": "ecd0aaa1-86e7-4f06-9f82-2985585c94a3"
        }
      },
      "webhook-endpoints": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/webhook-endpoints"
        }
      },
      "webhook-events": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/webhook-events"
        }
      },
      "products": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/products"
        }
      },
      "policies": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/policies"
        }
      },
      "users": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/users"
        }
      },
      "keys": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/keys"
        }
      },
      "licenses": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/licenses"
        }
      },
      "machines": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/machines"
        }
      },
      "tokens": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/tokens"
        }
      }
    }
  }
}

linkUpdate an account

Updates the specified account resource by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

linkAuthentication

  • linkBearer

    required

    An authentication token with admin privileges.

linkParameters

  • linkid

    string, required

    The identifier or slug of the account to be updated.

linkAttributes

  • linkname

    string, optional

    The name of the account.

  • linkslug

    string, optional

    The unique slug of the account.

  • linkprotected

    boolean, optional

    Whether or not the account is protected.

Definition

PATCH https://api.keygen.sh/v1/accounts/{ID} \
  -d '{ "data": { "type": "accounts", "attributes": {DATA} } }'

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2", {
  method: "PATCH",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  },
  body: JSON.stringify({
    "data": {
      "type": "accounts",
      "attributes": {
        "protected": true
      }
    }
  })
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2",
  method: .patch,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ],
  parameters: [
    "data": [
      "type": "accounts",
      "attributes": [
        "protected": true
      ]
    ]
  ],
  encoding: JSONEncoding.default
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl -X PATCH https://api.keygen.sh/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2 \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>' \
  -d '{
        "data": {
          "type": "accounts",
          "attributes": {
            "protected": true
          }
        }
      }'

Example response / 200 OK

{
  "data": {
    "id": "fff33d8f-11b8-428d-a949-db2b74d7c2f2",
    "type": "accounts",
    "links": {
      "self": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2"
    },
    "attributes": {
      "name": "Tesla",
      "slug": "tesla",
      "protected": true,
      "created": "<%= created %>",
      "updated": "<%= updated %>"
    },
    "relationships": {
      "billing": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/billing"
        },
        "data": {
          "type": "billings",
          "id": "00461c96-27c3-4c68-b180-e6b7bc13dfab"
        }
      },
      "plan": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/plan"
        },
        "data": {
          "type": "plans",
          "id": "ecd0aaa1-86e7-4f06-9f82-2985585c94a3"
        }
      },
      "webhook-endpoints": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/webhook-endpoints"
        }
      },
      "webhook-events": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/webhook-events"
        }
      },
      "products": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/products"
        }
      },
      "policies": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/policies"
        }
      },
      "users": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/users"
        }
      },
      "keys": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/keys"
        }
      },
      "licenses": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/licenses"
        }
      },
      "machines": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/machines"
        }
      },
      "tokens": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/tokens"
        }
      }
    }
  }
}

linkDelete an account

Permanently deletes an account.

This cannot be undone or recovered. This action also immediately deletes all resources that the account is associated with e.g. users, licenses, machines, etc.

linkAuthentication

  • linkBearer

    required

    An authentication token with admin privileges.

linkParameters

  • linkid

    string, required

    The identifier or slug of the account to be deleted.

Definition

DELETE https://api.keygen.sh/v1/accounts/{ID}

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2", {
  method: "DELETE",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2",
  method: .delete,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let status = response.response?.statusCode
}
curl -X DELETE https://api.keygen.sh/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2 \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 204 No Content

No content

linkAccount plan

The account's current subscription plan.

linkRetrieve plan

Retrieves the details of the account's subscription plan.

linkAuthentication

  • linkBearer

    required

    An authentication token with admin privileges.

linkParameters

  • linkid

    string, required

    The identifier or slug of the account.

Definition

GET https://api.keygen.sh/v1/accounts/{ID}/plan

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/plan", {
  method: "GET",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/plan",
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl https://api.keygen.sh/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/plan \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": {
    "id": "0e040820-aba5-4e0e-8947-b9f7cf76e484",
    "type": "plans",
    "links": {
      "self": "/v1/plans/0e040820-aba5-4e0e-8947-b9f7cf76e484"
    },
    "attributes": {
      "name": "Enterprise",
      "price": 24900,
      "trialDuration": 604800,
      "maxUsers": null,
      "maxPolicies": null,
      "maxLicenses": null,
      "maxProducts": 5,
      "created": "<%= created %>",
      "updated": "<%= created %>"
    }
  }
}

linkChange plan

Change the subscription plan for the account.

When an account switches subscription plans in the middle of a billing period, here’s what happens:

  • If the new plan has the same billing frequency as the old plan (for example, monthly to monthly, and so on), we immediately create a line item for the remaining portion of the current billing period at the new plan rate. At the next scheduled billing, the account is charged for the line item and the full charge for the upcoming period, less any account credits.
  • If the new plan has a different billing frequency from the old plan (for example, monthly to yearly, and so on), the first full period of the new plan begins immediately and the account is charged for the first period, less any account credits.

linkAuthentication

  • linkBearer

    required

    An authentication token with admin privileges.

linkParameters

  • linkid

    string, required

    The identifier or slug of the account.

linkRelationships

  • linkplan

    hash, required

    The plan to change to.

Definition

PUT https://api.keygen.sh/v1/accounts/{ID}/plan

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/plan", {
  method: "PUT",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  },
  body: JSON.stringify({
    "data": {
      "type": "plans",
      "id": "b624e344-0f2c-4861-90a3-85c2b015dd7a"
    }
  })
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/plan",
  method: .put,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ],
  parameters: [
    "data": [
      "type": "plans",
      "id": "b624e344-0f2c-4861-90a3-85c2b015dd7a"
    ]
  ],
  encoding: JSONEncoding.default
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl -X PUT https://api.keygen.sh/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/plan \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>' \
  -d '{
        "data": {
          "type": "plans",
          "id": "b624e344-0f2c-4861-90a3-85c2b015dd7a"
        }
      }'

Example response / 200 OK

{
  "data": {
    "id": "b624e344-0f2c-4861-90a3-85c2b015dd7a",
    "type": "plans",
    "links": {
      "self": "/v1/plans/b624e344-0f2c-4861-90a3-85c2b015dd7a"
    },
    "attributes": {
      "name": "Enterprise",
      "price": 24900,
      "maxUsers": null,
      "maxPolicies": null,
      "maxLicenses": null,
      "maxProducts": 5,
      "created": "<%= created %>",
      "updated": "<%= created %>"
    }
  }
}

linkAccount billing

The account's billing info.

linkAttributes

  • linksubscriptionStatus

    stringread only

    The current status of the subscription.

  • linksubscriptionPeriodStart

    timestampread only

    The current subscription period's start date.

  • linksubscriptionPeriodEnd

    timestampread only

    The current subscription period's end date.

  • linkcardExpiry

    timestampread only

    The expiration date of the card on file.

  • linkcardBrand

    stringread only

    The brand of the card on file.

  • linkcardLast4

    stringread only

    The last 4 digits of the card on file.

  • linkstate

    stringread only

    The current state of the account.

  • linkcreated

    timestampread only

    When the billing info was created.

  • linkupdated

    timestampread only

    When the billing info was last updated.

linkRelationships

  • linkaccount

    individual

    The account that the billing info belongs to.

  • linkplan

    individual

    The plan that the account is subscribed to.

Example object

{
  "data": {
    "id": "6d16fd37-ba65-4491-9742-74c057e36957",
    "type": "billings",
    "links": {
      "self": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/billing"
    },
    "attributes": {
      "subscriptionStatus": "trialing",
      "subscriptionPeriodStart": "<%= created %>",
      "subscriptionPeriodEnd": "<%= expiry %>",
      "cardExpiry": "2020-04-01T00:00:00.000Z",
      "cardBrand": "Visa",
      "cardLast4": "4242",
      "state": "subscribed",
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2"
        },
        "data": {
          "type": "accounts",
          "id": "fff33d8f-11b8-428d-a949-db2b74d7c2f2"
        }
      },
      "plan": {
        "links": {
          "related": "/v1/plans/40e07d64-ecc9-40ba-a26a-c137e164fdd4"
        },
        "data": {
          "type": "plans",
          "id": "40e07d64-ecc9-40ba-a26a-c137e164fdd4"
        }
      }
    }
  }
}

linkRetrieve billing

Retrieves the billing info for the account.

linkAuthentication

  • linkBearer

    required

    An authentication token with admin privileges.

linkParameters

  • linkid

    string, required

    The identifier or slug of the account.

Definition

GET https://api.keygen.sh/v1/accounts/{ID}/billing

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/billing", {
  method: "GET",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/billing",
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl https://api.keygen.sh/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/billing \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": {
    "id": "6d16fd37-ba65-4491-9742-74c057e36957",
    "type": "billings",
    "links": {
      "self": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/billing"
    },
    "attributes": {
      "subscriptionStatus": "trialing",
      "subscriptionPeriodStart": "<%= created %>",
      "subscriptionPeriodEnd": "<%= expiry %>",
      "cardExpiry": "2020-04-01T00:00:00.000Z",
      "cardBrand": "Visa",
      "cardLast4": "4242",
      "state": "subscribed",
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2"
        },
        "data": {
          "type": "accounts",
          "id": "fff33d8f-11b8-428d-a949-db2b74d7c2f2"
        }
      },
      "plan": {
        "links": {
          "related": "/v1/plans/40e07d64-ecc9-40ba-a26a-c137e164fdd4"
        },
        "data": {
          "type": "plans",
          "id": "40e07d64-ecc9-40ba-a26a-c137e164fdd4"
        }
      }
    }
  }
}

linkUpdate billing info

Update billing info for the account.

linkAuthentication

  • linkBearer

    required

    An authentication token with admin privileges.

linkParameters

  • linkid

    string, required

    The identifier or slug of the account.

linkAttributes

  • linktoken

    string, required

    A Stripe token representing the new card for the account.

Definition

PATCH https://api.keygen.sh/v1/accounts/{ID}/billing

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/billing", {
  method: "PATCH",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  },
  body: JSON.stringify({
    "data": {
      "type": "billings",
      "attributes": {
        "token": "tok_19bAUxBuIJAzxZqVkNh7ePHL"
      }
    }
  })
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/billing",
  method: .patch,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ],
  parameters: [
    "data": [
      "type": "billings",
      "attributes": [
        "token": "tok_19bAUxBuIJAzxZqVkNh7ePHL"
      ]
    ]
  ],
  encoding: JSONEncoding.default
).responseJSON { response in
    let json = JSON(data: response.data!)
}
curl -X PATCH https://api.keygen.sh/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/billing \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>' \
  -d '{
        "data": {
          "type": "billings",
          "attributes": {
            "token": "tok_19bAUxBuIJAzxZqVkNh7ePHL"
          }
        }
      }'

Example response / 202 Accepted

Accepted

linkAccount actions

Actions for the account resource.

linkPause subscription

Action to pause the account's subscription.

Be aware that this will immediately disable all of an account's resource endpoints until the account is unpaused.

linkAuthentication

  • linkBearer

    required

    An authentication token with admin privileges.

linkParameters

  • linkid

    string, required

    The identifier or slug of the account to be paused.

Definition

POST https://api.keygen.sh/v1/accounts/{ID}/actions/pause-subscription

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/actions/pause-subscription", {
  method: "POST",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})

const { meta, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/actions/pause-subscription",
  method: .post,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl -X POST https://api.keygen.sh/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/actions/pause-subscription \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "meta": {
    "status": "paused"
  }
}

linkResume subscription

Action to resume the account's paused subscription.

Be aware that the account will be billed on the same cycle that it was on before the account's subscription was paused if the account is unpaused before the old cycle ends – this may result in being billed upon resuming the subscription.

linkAuthentication

  • linkBearer

    required

    An authentication token with admin privileges.

linkParameters

  • linkid

    string, required

    The identifier or slug of the account to be resumed.

Definition

POST https://api.keygen.sh/v1/accounts/{ID}/actions/resume-subscription

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/actions/resume-subscription", {
  method: "POST",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})

const { meta, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/actions/resume-subscription",
  method: .post,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl -X POST https://api.keygen.sh/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/actions/resume-subscription \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "meta": {
    "status": "resumed"
  }
}

linkCancel subscription

Action to cancel the account's subscription.

Be aware that this will disable all of an account's resource endpoints at the end of the subscription billing period.

linkAuthentication

  • linkBearer

    required

    An authentication token with admin privileges.

linkParameters

  • linkid

    string, required

    The identifier or slug of the account to be canceled.

Definition

POST https://api.keygen.sh/v1/accounts/{ID}/actions/cancel-subscription

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/actions/cancel-subscription", {
  method: "POST",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})

const { meta, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/actions/cancel-subscription",
  method: .post,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl -X POST https://api.keygen.sh/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/actions/cancel-subscription \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "meta": {
    "status": "canceled"
  }
}

linkRenew subscription

Action to renew the account's canceled subscription.

Be aware that if the account's current plan is a paid plan, the account will be billed upon renewal.

linkAuthentication

  • linkBearer

    required

    An authentication token with admin privileges.

linkParameters

  • linkid

    string, required

    The identifier or slug of the account to be renewed.

Definition

POST https://api.keygen.sh/v1/accounts/{ID}/actions/renew-subscription

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/actions/renew-subscription", {
  method: "POST",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})

const { meta, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/actions/renew-subscription",
  method: .post,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl -X POST https://api.keygen.sh/v1/accounts/fff33d8f-11b8-428d-a949-db2b74d7c2f2/actions/renew-subscription \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "meta": {
    "status": "renewed"
  }
}

linkProducts

linkThe product object

Below you will find the various attributes for the product resource, as well as the product resource's relationships.

linkAttributes

  • linkname

    string

    The name of the product.

  • linkurl

    string

    A related URL for the product e.g. the marketing website, company website, etc.

  • linkplatforms

    array<string>

    An array of platforms the product supports.

  • linkmetadata

    hash

    Hash containing product metadata.

  • linkcreated

    timestampread only

    When the product was created.

  • linkupdated

    timestampread only

    When the product was last updated.

linkRelationships

  • linkaccount

    individual

    The account that the product belongs to.

  • linkpolicies

    collection

    The policies that are associated with the product.

  • linklicenses

    collection

    The licenses that are associated with the product.

  • linkmachines

    collection

    The machines that are associated with the product.

  • linkusers

    collection

    The users that own a license for the product.

  • linktokens

    collection

    The authentication tokens of the product.

Example object

{
  "data": {
    "id": "31339351-f7f5-4bdd-8346-5d8399a1ac07",
    "type": "products",
    "links": {
      "self": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07"
    },
    "attributes": {
      "name": "Product Hunt",
      "url": "https://producthunt.com",
      "platforms": ["iOS", "Android"],
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "policies": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/policies"
        }
      },
      "licenses": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/licenses"
        }
      },
      "machines": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/machines"
        }
      },
      "users": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/users"
        }
      },
      "tokens": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/tokens"
        }
      }
    }
  }
}

linkCreate a product

Creates a new product resource.

linkAuthentication

  • linkBearer

    required

    An authentication token with admin privileges.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

linkAttributes

  • linkname

    string, required

    The name of the product.

  • linkurl

    string, optional

    A related URL for the product e.g. the marketing website, company website, etc. Must be a valid URL.

  • linkplatforms

    array<string>, optional

    An array of platforms the product supports.

  • linkmetadata

    hash, optional

    Hash containing product metadata.

Definition

POST https://api.keygen.sh/v1/accounts/<%= account %>/products \
  -d '{ "data": { "type": "products", "attributes": {DATA} } }'

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/products", {
  method: "POST",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  },
  body: JSON.stringify({
    "data": {
      "type": "products",
      "attributes": {
        "name": "Product Hunt",
        "url": "https://producthunt.com",
        "platforms": ["iOS", "Android"]
      }
    }
  })
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/products",
  method: .post,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ],
  parameters: [
    "data": [
      "type": "products",
      "attributes": [
        "name": "Product Hunt",
        "url": "https://producthunt.com",
        "platforms": ["iOS", "Android"]
      ]
    ]
  ],
  encoding: JSONEncoding.default
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl -X POST https://api.keygen.sh/v1/accounts/<%= account %>/products \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>' \
  -d '{
        "data": {
          "type": "products",
          "attributes": {
            "name": "Product Hunt",
            "url": "https://producthunt.com",
            "platforms": ["iOS", "Android"]
          }
        }
      }'

Example response / 201 Created

{
  "data": {
    "id": "31339351-f7f5-4bdd-8346-5d8399a1ac07",
    "type": "products",
    "links": {
      "self": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07"
    },
    "attributes": {
      "name": "Product Hunt",
      "url": "https://producthunt.com",
      "platforms": ["iOS", "Android"],
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "policies": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/policies"
        }
      },
      "licenses": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/licenses"
        }
      },
      "machines": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/machines"
        }
      },
      "users": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/users"
        }
      },
      "tokens": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/tokens"
        }
      }
    }
  }
}

linkRetrieve a product

Retrieves the details of an existing product.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to view the resource: either an admin or the product.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

  • linkid

    string, required

    The identifier of the product to be retrieved.

Definition

GET https://api.keygen.sh/v1/accounts/<%= account %>/products/{ID}

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07", {
  method: "GET",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07",
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl https://api.keygen.sh/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07 \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": {
    "id": "31339351-f7f5-4bdd-8346-5d8399a1ac07",
    "type": "products",
    "links": {
      "self": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07"
    },
    "attributes": {
      "name": "Product Hunt",
      "url": "https://producthunt.com",
      "platforms": ["iOS", "Android"],
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "policies": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/policies"
        }
      },
      "licenses": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/licenses"
        }
      },
      "machines": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/machines"
        }
      },
      "users": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/users"
        }
      },
      "tokens": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/tokens"
        }
      }
    }
  }
}

linkUpdate a product

Updates the specified product resource by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to manage the resource: either an admin or the product.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

  • linkid

    string, required

    The identifier of the product to be updated.

linkAttributes

  • linkname

    string, optional

    The name of the product.

  • linkurl

    string, optional

    A related URL for the product e.g. the marketing website, company website, etc. Must be a valid URL.

  • linkplatforms

    array<string>, optional

    An array of platforms the product supports.

  • linkmetadata

    hash, optional

    Hash containing product metadata.

Definition

PATCH https://api.keygen.sh/v1/accounts/<%= account %>/products/{ID} \
  -d '{ "data": { "type": "products", "attributes": {DATA} } }'

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07", {
  method: "PATCH",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  },
  body: JSON.stringify({
    "data": {
      "type": "products",
      "attributes": {
        "platforms": [
          "iOS",
          "Android",
          "Windows"
        ]
      }
    }
  })
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07",
  method: .patch,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ],
  parameters: [
    "data": [
      "type": "products",
      "attributes": [
        "platforms": [
          "iOS",
          "Android",
          "Windows"
        ]
      ]
    ]
  ],
  encoding: JSONEncoding.default
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl -X PATCH https://api.keygen.sh/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07 \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>' \
  -d '{
        "data": {
          "type": "products",
          "attributes": {
            "platforms": [
              "iOS",
              "Android",
              "Windows"
            ]
          }
        }
      }'

Example response / 200 OK

{
  "data": {
    "id": "31339351-f7f5-4bdd-8346-5d8399a1ac07",
    "type": "products",
    "links": {
      "self": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07"
    },
    "attributes": {
      "name": "Product Hunt",
      "url": "https://producthunt.com",
      "platforms": ["iOS", "Android", "Windows"],
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= updated %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "policies": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/policies"
        }
      },
      "licenses": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/licenses"
        }
      },
      "machines": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/machines"
        }
      },
      "users": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/users"
        }
      },
      "tokens": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/tokens"
        }
      }
    }
  }
}

linkDelete a product

Permanently deletes a product. It cannot be undone. This action also immediately deletes any policies, licenses and machines that the product is associated with.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to manage the resource: either an admin or the product.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

  • linkid

    string, required

    The identifier of the product to be deleted.

Definition

DELETE https://api.keygen.sh/v1/accounts/<%= account %>/products/{ID}

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07", {
  method: "DELETE",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07",
  method: .delete,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let status = response.response?.statusCode
}
curl -X DELETE https://api.keygen.sh/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07 \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 204 No Content

No content

linkList all products

Returns a list of products. The products are returned sorted by creation date, with the most recent products appearing first.

linkAuthentication

  • linkBearer

    required

    An authentication token with admin privileges.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

linkFilters

  • linklimit

    integer, default is10

    A limit on the number of products to be returned. Limit must be a number between 1 and 100.

    https://api.keygen.sh/v1/accounts/<%= account %>/products?limit=25

  • linkpage

    hash

    Hash containing page size and page number. Page size must be a number between 1 and 100

    https://api.keygen.sh/v1/accounts/<%= account %>/products?page[size]=15&page[number]=2

Definition

GET https://api.keygen.sh/v1/accounts/<%= account %>/products{FILTERS}

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/products?limit=15", {
  method: "GET",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/products?limit=15",
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl https://api.keygen.sh/v1/accounts/<%= account %>/products?limit=15 -g \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": [
    {
      "id": "31339351-f7f5-4bdd-8346-5d8399a1ac07",
      "type": "products",
      "links": {
        "self": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07"
      },
      "attributes": {
        "name": "Product Hunt",
        "url": "https://producthunt.com",
        "platforms": ["iOS", "Android"],
        "metadata": {},
        "created": "<%= created %>",
        "updated": "<%= created %>"
      },
      "relationships": {
        "account": {
          "links": {
            "related": "/v1/accounts/<%= account %>"
          },
          "data": {
            "type": "accounts",
            "id": "<%= account %>"
          }
        },
        "policies": {
          "links": {
            "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/policies"
          }
        },
        "licenses": {
          "links": {
            "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/licenses"
          }
        },
        "machines": {
          "links": {
            "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/machines"
          }
        },
        "users": {
          "links": {
            "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/users"
          }
        },
        "tokens": {
          "links": {
            "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/tokens"
          }
        }
      }
    },
    …
  ]
}

linkGenerate a product token

Generates a new product token resource. Product tokens do not expire.

Product tokens should not be included in any client-facing code, as they offer full access to all of the product's resources. Only use these tokens server-side e.g. to consume webhooks or to create new resources in response to events from your payment provider.

linkAuthentication

  • linkBearer

    required

    An authentication token with admin privileges.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

  • linkid

    string, required

    The identifier of the product to generate a token for.

Definition

POST https://api.keygen.sh/v1/accounts/<%= account %>/products/{ID}/tokens

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/tokens", {
  method: "POST",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/tokens",
  method: .post,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl -X POST https://api.keygen.sh/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/tokens \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 201 Created

{
  "data": {
    "id": "07d52aa8-b96c-4b55-b05d-f5f570e1775a",
    "type": "tokens",
    "attributes": {
      "token": "cbe10f1ab9da4580bf5428cd7c1161f0.07d52aa8b96c4b55b05df5f570e1775a.4TzUcN9xMV2cUVT3AuDbPx8XWXnDRF4TzUcN9xMV2cUVT3AuDbPx8XWXnDRFnReibxxgBxXaY2gpb7DRDkUmZpyYi2sXzYfyVL4buWtbgyFD9zbd1319f14b90de1cv1",
      "expiry": "<%= expiry %>",
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "bearer": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07"
        },
        "data": {
          "type": "products",
          "id": "31339351-f7f5-4bdd-8346-5d8399a1ac07"
        }
      }
    }
  }
}

linkPolicies

linkThe policy object

Below you will find the various attributes for the policy resource, as well as the policy resource's relationships. Your policies define the different types of licenses that a given product offers.

linkAttributes

  • linkname

    string

    The name of the policy.

  • linkduration

    integer

    The duration for the policy in seconds. When a license implements the policy, the license's expiry is calculated with this value. If null, licenses will never expire.

  • linkstrict

    boolean, default isfalse

    When enabled, a license that implements the policy will be considered invalid if its machine limit is surpassed. In addition, strict requires a license to have at least 1 machine associated with it in order to pass validation.

  • linkfloating

    boolean, default isfalse

    When enabled, a license that implements the policy will be valid across multiple machines. Though this is not enforced i.e. it does not invalidate a license if it's associated with more than 1 machine unless the policy is strict.

  • linkrequireCheckIn

    boolean, default isfalse

    When enabled, a license that implements the policy will require check-in at a predefined interval to continue to pass validation i.e. if a license misses a check-in, it will be invalidated.

  • linkcheckInInterval

    string

    One of day, week, month or year. The frequency with which a license should check-in.

  • linkcheckInIntervalCount

    integer

    The number of intervals (specified in the check-in interval property) between each required check-in. For example, checkInInterval=week and checkInIntervalCount=2 requires check-in every 2 weeks. Must be a number between 1 and 365 inclusive.

  • linkusePool

    boolean, default isfalse

    Whether or not to pull license keys from a finite pool of pre-determined keys. This is useful for invite-only programs such as a private beta, when you need a limited set of licenses, or when you want to define the keys manually. This cannot be changed later on.

  • linkmaxMachines

    integer, default is1

    The maximum number of machines a license implementing the policy can activate per-user.

  • linkencrypted

    boolean, default isfalse

    Whether or not to encrypt license keys. When enabled, a license's key will only be available to read directly after creation via the response payload. Not compatible with a pooled policy. This cannot be changed later on.

  • linkprotected

    boolean, default isfalse

    Whether or not the policy is protected. A protected policy disallows users the ability to create and manage licenses themselves, useful in situations where Keygen is only managed server-side or when you aren't listening for the appropriate user-initiated webhook events. If the account is protected, all policies automatically inherit that value.

  • linkmetadata

    hash

    Hash containing policy metadata.

  • linkcreated

    timestampread only

    When the policy was created.

  • linkupdated

    timestampread only

    When the policy was last updated.

linkRelationships

  • linkaccount

    individual

    The account that the policy belongs to.

  • linkproduct

    individual

    The product that the policy is associated with.

  • linkpool

    collection

    The pool of pre-determined keys for the policy.

  • linklicenses

    collection

    The licenses that implement the policy.

Example object

{
  "data": {
    "id": "0b4b1a9a-e25a-4f14-a95e-d9dd378d6065",
    "type": "policies",
    "links": {
      "self": "/v1/accounts/<%= account %>/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065"
    },
    "attributes": {
      "name": "Premium Add-On",
      "duration": 1209600,
      "strict": false,
      "floating": true,
      "requireCheckIn": false,
      "checkInInterval": null,
      "checkInIntervalCount": null,
      "usePool": false,
      "maxMachines": 5,
      "encrypted": true,
      "protected": false,
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "product": {
        "links": {
          "related": "/v1/accounts/<%= account %>/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/product"
        },
        "data": {
          "type": "products",
          "id": "3ab38aae-bbf7-4846-9c32-af9d94bf5ad4"
        }
      },
      "pool": {
        "links": {
          "related": "/v1/accounts/<%= account %>/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/pool"
        }
      },
      "licenses": {
        "links": {
          "related": "/v1/accounts/<%= account %>/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/licenses"
        }
      }
    }
  }
}

linkCreate a policy

Creates a new policy resource.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to manage the resource: either an admin or the product it belongs to.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

linkAttributes

  • linkname

    string, required

    The name of the policy.

  • linkduration

    integer, optional

    The duration for the policy in seconds. When a license implements the policy, the license's expiry is calculated with this value. If null, licenses will never expire.

  • linkstrict

    boolean, optional

    When enabled, a license that implements the policy will be considered invalid if its machine limit is surpassed. In addition, strict requires a license to have at least 1 machine associated with it in order to pass validation.

  • linkfloating

    boolean, optional

    When enabled, a license that implements the policy will be valid across multiple machines. Though this is not enforced i.e. it does not invalidate a license if it's associated with more than 1 machine unless the policy is strict.

  • linkrequireCheckIn

    boolean, optional

    When enabled, a license that implements the policy will require check-in at a predefined interval to continue to pass validation i.e. if a license misses a check-in, it will be invalidated.

  • linkcheckInInterval

    string, optional

    One of day, week, month or year. The frequency with which a license should check-in.

  • linkcheckInIntervalCount

    integer, optional

    The number of intervals (specified in the check-in interval property) between each required check-in. For example, checkInInterval=week and checkInIntervalCount=2 requires check-in every 2 weeks. Must be a number between 1 and 365 inclusive.

  • linkusePool

    boolean, optional

    Whether or not to pull license keys from a finite pool of pre-determined keys. This is useful for invite-only programs such as a private beta, when you need a limited set of licenses, or when you want to define the keys manually. This cannot be changed later on.

  • linkmaxMachines

    integer, optional

    The maximum number of machines a license implementing the policy can activate per-user.

  • linkencrypted

    boolean, optional

    Whether or not to encrypt license keys. When enabled, a license's key will only be available to read directly after creation via the response payload. Not compatible with a pooled policy. This cannot be changed later on.

  • linkprotected

    boolean, optional

    Whether or not the policy is protected. A protected policy disallows users the ability to create licenses themselves, useful in situations where Keygen is only managed server-side. If the account is protected, all policies automatically inherit that value.

  • linkmetadata

    hash, optional

    Hash containing policy metadata.

linkRelationships

  • linkproduct

    hash, required

    The product the policy is for.

Definition

POST https://api.keygen.sh/v1/accounts/<%= account %>/policies \
  -d '{ "data": { "type": "policies", "attributes": {DATA}, "relationships": {DATA} } }'

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/policies", {
  method: "POST",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  },
  body: JSON.stringify({
    "data": {
      "type": "policies",
      "attributes": {
        "name": "Basic"
      },
      "relationships": {
        "product": {
          "data": { "type": "product", "id": "3ab38aae-bbf7-4846-9c32-af9d94bf5ad4" }
        }
      }
    }
  })
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/policies",
  method: .post,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ],
  parameters: [
    "data": [
      "type": "policies",
      "attributes": [
        "name": "Basic"
      ],
      "relationships": [
        "product": [
          "data": ["type": "product", "id": "3ab38aae-bbf7-4846-9c32-af9d94bf5ad4"]
        ]
      ]
    ]
  ],
  encoding: JSONEncoding.default
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl -X POST https://api.keygen.sh/v1/accounts/<%= account %>/policies \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>' \
  -d '{
        "data": {
          "type": "policies",
          "attributes": {
            "name": "Basic"
          },
          "relationships": {
            "product": {
              "data": { "type": "product", "id": "3ab38aae-bbf7-4846-9c32-af9d94bf5ad4" }
            }
          }
        }
      }'

Example response / 201 Created

{
  "data": {
    "id": "0b4b1a9a-e25a-4f14-a95e-d9dd378d6065",
    "type": "policies",
    "links": {
      "self": "/v1/accounts/<%= account %>/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065"
    },
    "attributes": {
      "name": "Basic",
      "duration": null,
      "strict": false,
      "floating": false,
      "requireCheckIn": false,
      "checkInInterval": null,
      "checkInIntervalCount": null,
      "usePool": false,
      "maxMachines": 1,
      "encrypted": false,
      "protected": false,
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "product": {
        "links": {
          "related": "/v1/accounts/<%= account %>/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/product"
        },
        "data": {
          "type": "products",
          "id": "3ab38aae-bbf7-4846-9c32-af9d94bf5ad4"
        }
      },
      "pool": {
        "links": {
          "related": "/v1/accounts/<%= account %>/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/pool"
        }
      },
      "licenses": {
        "links": {
          "related": "/v1/accounts/<%= account %>/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/licenses"
        }
      }
    }
  }
}

linkRetrieve a policy

Retrieves the details of an existing policy.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to view the resource: either an admin or the product it belongs to.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

  • linkid

    string, required

    The identifier of the policy to be retrieved.

Definition

GET https://api.keygen.sh/v1/accounts/<%= account %>/policies/{ID}

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065", {
  method: "GET",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065",
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl https://api.keygen.sh/v1/accounts/<%= account %>/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065 \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": {
    "id": "0b4b1a9a-e25a-4f14-a95e-d9dd378d6065",
    "type": "policies",
    "links": {
      "self": "/v1/accounts/<%= account %>/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065"
    },
    "attributes": {
      "name": "Premium Add-On",
      "duration": 1209600,
      "strict": false,
      "floating": true,
      "requireCheckIn": false,
      "checkInInterval": null,
      "checkInIntervalCount": null,
      "usePool": false,
      "maxMachines": 5,
      "encrypted": true,
      "protected": false,
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "product": {
        "links": {
          "related": "/v1/accounts/<%= account %>/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/product"
        },
        "data": {
          "type": "products",
          "id": "3ab38aae-bbf7-4846-9c32-af9d94bf5ad4"
        }
      },
      "pool": {
        "links": {
          "related": "/v1/accounts/<%= account %>/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/pool"
        }
      },
      "licenses": {
        "links": {
          "related": "/v1/accounts/<%= account %>/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/licenses"
        }
      }
    }
  }
}

linkUpdate a policy

Updates the specified policy resource by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to manage the resource: either an admin or the product it belongs to.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

  • linkid

    string, required

    The identifier of the policy to be updated.

linkAttributes

  • linkname

    string, optional

    The name of the policy.

  • linkduration

    integer, optional

    The duration for the policy in seconds. When a license implements the policy, the license's expiry is calculated with this value. If null, licenses will never expire.

  • linkstrict

    boolean, optional

    When enabled, a license that implements the policy will be considered invalid if its machine limit is surpassed. In addition, strict requires a license to have at least 1 machine associated with it in order to pass validation.

  • linkfloating

    boolean, optional

    When enabled, a license that implements the policy will be valid across multiple machines. Though this is not enforced i.e. it does not invalidate a license if it's associated with more than 1 machine unless the policy is strict.

  • linkrequireCheckIn

    boolean, optional

    When enabled, a license that implements the policy will require check-in at a predefined interval to continue to pass validation i.e. if a license misses a check-in, it will be invalidated.

  • linkcheckInInterval

    string, optional

    One of day, week, month or year. The frequency with which a license should check-in.

  • linkcheckInIntervalCount

    integer, optional

    The number of intervals (specified in the check-in interval property) between each required check-in. For example, checkInInterval=week and checkInIntervalCount=2 requires check-in every 2 weeks. Must be a number between 1 and 365 inclusive.

  • linkmaxMachines

    integer, optional

    The maximum number of machines a license implementing the policy can activate per-user.

  • linkprotected

    boolean, optional

    Whether or not the policy is protected. A protected policy disallows users the ability to create licenses themselves, useful in situations where Keygen is only managed server-side. If the account is protected, all policies automatically inherit that value.

  • linkmetadata

    hash, optional

    Hash containing policy metadata.

Definition

PATCH https://api.keygen.sh/v1/accounts/<%= account %>/policies/{ID} \
  -d '{ "data": { "type": "policies", "attributes": {DATA} } }'

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065", {
  method: "PATCH",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  },
  body: JSON.stringify({
    "data": {
      "type": "policies",
      "attributes": {
        "maxMachines": 15
      }
    }
  })
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065",
  method: .patch,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ],
  parameters: [
    "data": [
      "type": "policies",
      "attributes": [
        "maxMachines": 15
      ]
    ]
  ],
  encoding: JSONEncoding.default
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl -X PATCH https://api.keygen.sh/v1/accounts/<%= account %>/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065 \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>' \
  -d '{
        "data": {
          "type": "policies",
          "attributes": {
            "maxMachines": 15
          }
        }
      }'

Example response / 200 OK

{
  "data": {
    "id": "0b4b1a9a-e25a-4f14-a95e-d9dd378d6065",
    "type": "policies",
    "links": {
      "self": "/v1/accounts/<%= account %>/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065"
    },
    "attributes": {
      "name": "Premium Add-On",
      "duration": 1209600,
      "strict": false,
      "floating": true,
      "requireCheckIn": false,
      "checkInInterval": null,
      "checkInIntervalCount": null,
      "usePool": false,
      "maxMachines": 15,
      "encrypted": true,
      "protected": false,
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "product": {
        "links": {
          "related": "/v1/accounts/<%= account %>/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/product"
        },
        "data": {
          "type": "products",
          "id": "3ab38aae-bbf7-4846-9c32-af9d94bf5ad4"
        }
      },
      "pool": {
        "links": {
          "related": "/v1/accounts/<%= account %>/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/pool"
        }
      },
      "licenses": {
        "links": {
          "related": "/v1/accounts/<%= account %>/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/licenses"
        }
      }
    }
  }
}

linkDelete a policy

Permanently deletes a policy. It cannot be undone. This action also immediately deletes any licenses that the policy is associated with.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to manage the resource: either an admin or the product it belongs to.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

  • linkid

    string, required

    The identifier of the policy to be deleted.

Definition

DELETE https://api.keygen.sh/v1/accounts/<%= account %>/policies/{ID}

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065", {
  method: "DELETE",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065",
  method: .delete,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let status = response.response?.statusCode
}
curl -X DELETE https://api.keygen.sh/v1/accounts/<%= account %>/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065 \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 204 No Content

No content

linkList all policies

Returns a list of policies. The policies are returned sorted by creation date, with the most recent policies appearing first. Resources are automatically scoped to the authenticated bearer e.g. when authenticated as a product, only policies of that specific product will be listed.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to view the resources: either an admin or a product.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

linkFilters

  • linklimit

    integer, default is10

    A limit on the number of policies to be returned. Limit must be a number between 1 and 100.

    https://api.keygen.sh/v1/accounts/<%= account %>/policies?limit=25

  • linkpage

    hash

    Hash containing page size and page number. Page size must be a number between 1 and 100

    https://api.keygen.sh/v1/accounts/<%= account %>/policies?page[size]=15&page[number]=2

  • linkproduct

    string

    The identifier of the product to filter by.

    https://api.keygen.sh/v1/accounts/<%= account %>/policies?product=3ab38aae-bbf7-4846-9c32-af9d94bf5ad4

Definition

GET https://api.keygen.sh/v1/accounts/<%= account %>/policies{FILTERS}

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/policies?limit=15", {
  method: "GET",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/policies?limit=15",
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl https://api.keygen.sh/v1/accounts/<%= account %>/policies?limit=15 -g \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": [
    {
      "id": "0b4b1a9a-e25a-4f14-a95e-d9dd378d6065",
      "type": "policies",
      "links": {
        "self": "/v1/accounts/<%= account %>/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065"
      },
      "attributes": {
        "name": "Premium Add-On",
        "duration": 1209600,
        "strict": false,
        "floating": true,
        "requireCheckIn": false,
        "checkInInterval": null,
        "checkInIntervalCount": null,
        "usePool": false,
        "maxMachines": 5,
        "encrypted": true,
        "protected": false,
        "metadata": {},
        "created": "<%= created %>",
        "updated": "<%= created %>"
      },
      "relationships": {
        "account": {
          "links": {
            "related": "/v1/accounts/<%= account %>"
          },
          "data": {
            "type": "accounts",
            "id": "<%= account %>"
          }
        },
        "product": {
          "links": {
            "related": "/v1/accounts/<%= account %>/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/product"
          },
          "data": {
            "type": "products",
            "id": "3ab38aae-bbf7-4846-9c32-af9d94bf5ad4"
          }
        },
        "pool": {
          "links": {
            "related": "/v1/accounts/<%= account %>/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/pool"
          }
        },
        "licenses": {
          "links": {
            "related": "/v1/accounts/<%= account %>/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/licenses"
          }
        }
      }
    },
    …
  ]
}

linkPop key from pool

Pop off (delete) a key from the policy's pool of pre-determined keys. The returned key is only available directly after a pop, similar to authentication tokens. This cannot be undone.

This action does not create a license resource. What you do with the key after a pop is up to you e.g. create a license with it, discard it, etc. To pop a key and create a license in a single action, simply create a license that implements the pooled policy.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to manage the resource: either an admin or the product it belongs to.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

  • linkid

    string, required

    The identifier of the policy to be retrieved.

Definition

DELETE https://api.keygen.sh/v1/accounts/<%= account %>/policies/a5a154d2-f026-40fa-bc8d-a7e3ca415298/pool

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/policies/a5a154d2-f026-40fa-bc8d-a7e3ca415298/pool", {
  method: "DELETE",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/policies/a5a154d2-f026-40fa-bc8d-a7e3ca415298/pool",
  method: .delete,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl -X DELETE https://api.keygen.sh/v1/accounts/<%= account %>/policies/a5a154d2-f026-40fa-bc8d-a7e3ca415298/pool \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": {
    "id": "6331bcae-73c1-4a7e-bf02-bbf77cbb81d7",
    "type": "keys",
    "links": {
      "self": "/v1/accounts/<%= account %>/keys/6331bcae-73c1-4a7e-bf02-bbf77cbb81d7"
    },
    "attributes": {
      "key": "B8A5-91D7-CB9A-DAE4-4F6E-1128",
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "product": {
        "links": {
          "related": "/v1/accounts/<%= account %>/keys/6e936a61-94ad-44d1-88ac-88da9f10eca7/product"
        },
        "data": {
          "type": "products",
          "id": "1f286fb6-c9bb-498b-a4e7-6c67748b1f4f"
        }
      },
      "policy": {
        "links": {
          "related": "/v1/accounts/<%= account %>/keys/6e936a61-94ad-44d1-88ac-88da9f10eca7/policy"
        },
        "data": {
          "type": "policies",
          "id": "a5a154d2-f026-40fa-bc8d-a7e3ca415298"
        }
      }
    }
  }
}

linkUsers

linkThe user object

Below you will find the various attributes for the user resource, as well as the user resource's relationships. To modify a relationship, you will need to use the canonical link for the given resource.

linkAttributes

  • linkfullName

    stringread only

    The full name of the user.

  • linkfirstName

    string

    The first name of the user.

  • linklastName

    string

    The last name of the user.

  • linkemail

    string

    The unique email of the user.

  • linkrole

    string

    The role of the user.

  • linkmetadata

    hash

    Hash containing user metadata.

  • linkcreated

    timestampread only

    When the user was created.

  • linkupdated

    timestampread only

    When the user was last updated.

linkRelationships

  • linkaccount

    individual

    The account that the user belongs to.

  • linkproducts

    collection

    The products that the user is associated with.

  • linklicenses

    collection

    The licenses that the user owns.

  • linkmachines

    collection

    The machines that the user owns.

  • linktokens

    collection

    The authentication tokens of the user.

Example object

{
  "data": {
    "id": "a5a154d2-f026-40fa-bc8d-a7e3ca415298",
    "type": "users",
    "attributes": {
      "fullName": "John Doe",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "role": "user",
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "products": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/products"
        }
      },
      "licenses": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/licenses"
        }
      },
      "machines": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/machines"
        }
      },
      "tokens": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/tokens"
        }
      }
    }
  }
}

linkCreate a user

Creates a new user resource.

linkAuthentication

  • linkNone

    When the account is unprotected, no authentication is required and anybody may create new a user.

  • linkBearer

    required

    When the account is protected, an authentication token with admin privileges or a product token is required.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

linkAttributes

  • linkfirstName

    string, required

    The first name of the user.

  • linklastName

    string, required

    The last name of the user.

  • linkemail

    string, required

    The unique email of the user.

  • linkpassword

    string, required

    The password for the user.

  • linkrole

    string, default isuserprotected

    The role of the user. Can be either user or admin.

  • linkmetadata

    hash, optional

    Hash containing user metadata.

Definition

POST https://api.keygen.sh/v1/accounts/<%= account %>/users \
  -d '{ "data": { "type": "users", "attributes": {DATA}, "relationships": {DATA} } }'

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/users", {
  method: "POST",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json"
  },
  body: JSON.stringify({
    "data": {
      "type": "users",
      "attributes": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "[email protected]",
        "password": "secret"
      }
    }
  })
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/users",
  method: .post,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json"
  ],
  parameters: [
    "data": [
      "type": "users",
      "attributes": [
        "firstName": "John",
        "lastName": "Doe",
        "email": "[email protected]",
        "password": "secret"
      ]
    ]
  ],
  encoding: JSONEncoding.default
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl -X POST https://api.keygen.sh/v1/accounts/<%= account %>/users \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -d '{
        "data": {
          "type": "users",
          "attributes": {
            "firstName": "John",
            "lastName": "Doe",
            "email": "[email protected]",
            "password": "secret"
          }
        }
      }'

Example response / 201 Created

{
  "data": {
    "id": "a5a154d2-f026-40fa-bc8d-a7e3ca415298",
    "type": "users",
    "attributes": {
      "fullName": "John Doe",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "role": "user",
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "products": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/products"
        }
      },
      "licenses": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/licenses"
        }
      },
      "machines": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/machines"
        }
      },
      "tokens": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/tokens"
        }
      }
    }
  }
}

linkRetrieve a user

Retrieves the details of an existing user.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to manage the resource: either an admin, the user, or a product.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

  • linkid

    string, required

    The identifier of the user to be retrieved.

Definition

GET https://api.keygen.sh/v1/accounts/<%= account %>/users/{ID}

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298", {
  method: "GET",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298",
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl https://api.keygen.sh/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298 \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": {
    "id": "a5a154d2-f026-40fa-bc8d-a7e3ca415298",
    "type": "users",
    "attributes": {
      "fullName": "John Doe",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "role": "user",
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "products": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/products"
        }
      },
      "licenses": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/licenses"
        }
      },
      "machines": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/machines"
        }
      },
      "tokens": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/tokens"
        }
      }
    }
  }
}

linkUpdate a user

Updates the specified user resource by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to manage the resource: either an admin, the user, or a product.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

  • linkid

    string, required

    The identifier of the user to be updated.

linkAttributes

  • linkfirstName

    string, optional

    The first name of the user.

  • linklastName

    string, optional

    The last name of the user.

  • linkemail

    string, optional

    The unique email of the user.

  • linkrole

    stringprotected

    The role of the user. Can be either user or admin.

  • linkmetadata

    hash, optionalprotected

    Hash containing user metadata.

Definition

PATCH https://api.keygen.sh/v1/accounts/<%= account %>/users/{ID} \
  -d '{ "data": { "type": "users", "attributes": {DATA}, "relationships": {DATA} } }'

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298", {
  method: "PATCH",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  },
  body: JSON.stringify({
    "data": {
      "type": "users",
      "attributes": {
        "metadata": {
          "nickname": "Jack"
        }
      }
    }
  })
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298",
  method: .patch,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ],
  parameters: [
    "data": [
      "type": "users",
      "attributes": [
        "metadata": [
          "nickname": "Jack"
        ]
      ]
    ]
  ],
  encoding: JSONEncoding.default
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl -X PATCH https://api.keygen.sh/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298 \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>' \
  -d '{
        "data": {
          "type": "users",
          "attributes": {
            "metadata": {
              "nickname": "Jack"
            }
          }
        }
      }'

Example response / 200 OK

{
  "data": {
    "id": "a5a154d2-f026-40fa-bc8d-a7e3ca415298",
    "type": "users",
    "attributes": {
      "fullName": "John Doe",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "role": "user",
      "metadata": {
        "nickname": "Jack"
      },
      "created": "<%= created %>",
      "updated": "<%= updated %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "products": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/products"
        }
      },
      "licenses": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/licenses"
        }
      },
      "machines": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/machines"
        }
      },
      "tokens": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/tokens"
        }
      }
    }
  }
}

linkDelete a user

Permanently deletes a user. It cannot be undone. This action also immediately deletes any licenses and machines that the user is associated with.

linkAuthentication

  • linkBearer

    required

    An authentication token with admin privileges.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

  • linkid

    string, required

    The identifier of the user to be deleted.

Definition

DELETE https://api.keygen.sh/v1/accounts/<%= account %>/users/{ID}

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298", {
  method: "DELETE",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298",
  method: .delete,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let status = response.response?.statusCode
}
curl -X DELETE https://api.keygen.sh/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298 \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 204 No Content

No content

linkList all users

Returns a list of users. The users are returned sorted by creation date, with the most recent users appearing first. Resources are automatically scoped to the authenticated bearer e.g. when authenticated as a product, only users of that specific product will be listed.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to view the resources: either an admin or a product.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

linkFilters

  • linklimit

    integer, default is10

    A limit on the number of users to be returned. Limit must be a number between 1 and 100.

    https://api.keygen.sh/v1/accounts/<%= account %>/users?limit=25

  • linkpage

    hash

    Hash containing page size and page number. Page size must be a number between 1 and 100

    https://api.keygen.sh/v1/accounts/<%= account %>/users?page[size]=15&page[number]=2

  • linkproduct

    string

    The identifier of the product to filter by.

    https://api.keygen.sh/v1/accounts/<%= account %>/users?product=c6772cd4-c89c-45fa-ab19-395087d79a2d

  • linkroles

    array, default isuser

    Array containing role names to filter by. The following roles are available: admin, user.

    https://api.keygen.sh/v1/accounts/<%= account %>/users?roles[]=admin&roles[]=user

Definition

GET https://api.keygen.sh/v1/accounts/<%= account %>/users{FILTERS}

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/users?limit=15", {
  method: "GET",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/users?limit=15",
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl https://api.keygen.sh/v1/accounts/<%= account %>/users?limit=15 -g \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": [
    {
      "id": "a5a154d2-f026-40fa-bc8d-a7e3ca415298",
      "type": "users",
      "attributes": {
        "fullName": "John Doe",
        "firstName": "John",
        "lastName": "Doe",
        "email": "[email protected]",
        "role": "user",
        "metadata": {},
        "created": "<%= created %>",
        "updated": "<%= created %>"
      },
      "relationships": {
        "account": {
          "links": {
            "related": "/v1/accounts/<%= account %>"
          },
          "data": {
            "type": "accounts",
            "id": "<%= account %>"
          }
        },
        "products": {
          "links": {
            "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/products"
          }
        },
        "licenses": {
          "links": {
            "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/licenses"
          }
        },
        "machines": {
          "links": {
            "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/machines"
          }
        },
        "tokens": {
          "links": {
            "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/tokens"
          }
        }
      }
    },
    …
  ]
}

linkUser actions

Actions for the user resource.

linkUpdate password

Action to update the user's password. A user's password can only be updated when authenticated as the given user.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to manage the resource: the user.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

  • linkid

    string, required

    The identifier of the user to be retrieved.

linkMeta

  • linkoldPassword

    string, required

    The current password for the user.

  • linknewPassword

    string, required

    The new password for the user.

Definition

POST https://api.keygen.sh/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/actions/update-password \
  -d '{ "meta": {DATA} }'

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/actions/update-password", {
  method: "POST",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  },
  body: JSON.stringify({
    "meta": {
      "oldPassword": "password123",
      "newPassword": "Ep66YCGTD*kc=4AFotPf;[email protected]"
    }
  })
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/actions/update-password",
  method: .post,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ],
  parameters: [
    "meta": [
      "oldPassword": "password123",
      "newPassword": "Ep66YCGTD*kc=4AFotPf;[email protected]"
    ]
  ],
  encoding: JSONEncoding.default
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl -X POST https://api.keygen.sh/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/actions/update-password \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>' \
  -d '{
        "meta": {
          "oldPassword": "password123",
          "newPassword": "Ep66YCGTD*kc=4AFotPf;[email protected]"
        }
      }'

Example response / 200 OK

{
  "data": {
    "id": "a5a154d2-f026-40fa-bc8d-a7e3ca415298",
    "type": "users",
    "attributes": {
      "fullName": "John Doe",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "role": "user",
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= updated %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "products": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/products"
        }
      },
      "licenses": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/licenses"
        }
      },
      "machines": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/machines"
        }
      },
      "tokens": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/tokens"
        }
      }
    }
  }
}

linkReset password

Action to reset the user's password. Password reset tokens expire 24 hours after requesting the reset.

linkAuthentication

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

  • linkid

    string, required

    The identifier of the user to be retrieved.

linkMeta

  • linkpasswordResetToken

    string, required

    The password reset token emailed to the user.

  • linknewPassword

    string, required

    The new password for the user.

Definition

POST https://api.keygen.sh/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/actions/reset-password \
  -d '{ "meta": {DATA} }'

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/actions/reset-password", {
  method: "POST",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json"
  },
  body: JSON.stringify({
    "meta": {
      "passwordResetToken": "a9f93c31b41642248db99fc04f4e8482.a5a154d2f02640fabc8da7e3ca415298.96d846eb5cfa38e7282b8eb406926c23cb38edf73c9e15847ac8760427003f5612c6efb5a9005f162462079af2303b79b84d0e78b1aba4c72a7cef7c984d5fv1",
      "newPassword": "Ep66YCGTD*kc=4AFotPf;[email protected]"
    }
  })
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/actions/reset-password",
  method: .post,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json"
  ],
  parameters: [
    "meta": [
      "passwordResetToken": "a9f93c31b41642248db99fc04f4e8482.a5a154d2f02640fabc8da7e3ca415298.96d846eb5cfa38e7282b8eb406926c23cb38edf73c9e15847ac8760427003f5612c6efb5a9005f162462079af2303b79b84d0e78b1aba4c72a7cef7c984d5fv1",
      "newPassword": "Ep66YCGTD*kc=4AFotPf;[email protected]"
    ]
  ],
  encoding: JSONEncoding.default
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl -X POST https://api.keygen.sh/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/actions/reset-password \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -d '{
        "meta": {
          "passwordResetToken": "a9f93c31b41642248db99fc04f4e8482.a5a154d2f02640fabc8da7e3ca415298.96d846eb5cfa38e7282b8eb406926c23cb38edf73c9e15847ac8760427003f5612c6efb5a9005f162462079af2303b79b84d0e78b1aba4c72a7cef7c984d5fv1",
          "newPassword": "Ep66YCGTD*kc=4AFotPf;[email protected]"
        }
      }'

Example response / 200 OK

{
  "data": {
    "id": "a5a154d2-f026-40fa-bc8d-a7e3ca415298",
    "type": "users",
    "attributes": {
      "fullName": "John Doe",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "role": "user",
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= updated %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "products": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/products"
        }
      },
      "licenses": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/licenses"
        }
      },
      "machines": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/machines"
        }
      },
      "tokens": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/tokens"
        }
      }
    }
  }
}

linkLicenses

linkThe license object

Below you will find the various attributes for the license resource, as well as the license resource's relationships. A license is an implementation of a product's policy.

linkAttributes

  • linkkey

    string

    The unique key string for the license. If encrypted, this attribute is only available to read directly after license creation.

  • linkexpiry

    timestamp

    When the license will expire.

  • linksuspended

    boolean

    Whether or not the license is suspended. A suspended license will always fail validation.

  • linkencrypted

    booleanread only

    Whether or not the license is encrypted. This is inherited from the policy.

  • linklastCheckIn

    timestampread only

    When the license was last checked-in. This is null if the policy does not require check-ins.

  • linknextCheckIn

    timestampread only

    The time at which the license is required to check-in by. This is null if the policy does not require check-ins.

  • linkmetadata

    hash

    Hash containing license metadata.

  • linkcreated

    timestampread only

    When the license was created.

  • linkupdated

    timestampread only

    When the license was last updated.

linkRelationships

  • linkaccount

    individual

    The account that the license belongs to.

  • linkproduct

    individual

    The product that the license is associated with.

  • linkpolicy

    individual

    The policy that the license implements.

  • linkuser

    individual

    The user that owns the license.

  • linkmachines

    collection

    The machines that the license is associated with.

Example object

{
  "data": {
    "id": "b18e3f3a-330c-4d8d-ae2e-014db21fa827",
    "type": "licenses",
    "links": {
      "self": "/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827"
    },
    "attributes": {
      "key": "9581b92724204b63bb00d7652ef4b95b-b4fdedeb77a5dc2b57154ac881771867-1b6653b4a9f0ba7c7ce5f4d38430101a-84d547067f848e5ca6cdce667ccaf9v1",
      "expiry": "<%= expiry %>",
      "suspended": false,
      "encrypted": false,
      "lastCheckIn": null,
      "nextCheckIn": null,
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "product": {
        "links": {
          "related": "/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/product"
        },
        "data": {
          "type": "products",
          "id": "eb4e14a7-ea41-4ede-b3fe-5e835c17156b"
        }
      },
      "policy": {
        "links": {
          "related": "/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/policy"
        },
        "data": {
          "type": "policies",
          "id": "70af414d-6152-4ff1-892b-15a40ada6b4e"
        }
      },
      "user": {
        "links": {
          "related": "/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/user"
        },
        "data": {
          "type": "users",
          "id": "e8bf27c0-5f9c-4135-a65c-f52706c5fd4c"
        }
      },
      "machines": {
        "links": {
          "related": "/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/machines"
        }
      }
    }
  }
}

linkCreate a license

Creates a new license resource.

When creating a license for a pooled policy, the key will be taken from the remaining keys in the pool. If the pool is empty, an error will be returned until more keys are added to the pool.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to manage the resource: either an admin, the product it belongs to, or if the license's policy is unprotected, the user it belongs to.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

linkAttributes

  • linkkey

    string, optional

    A unique pre-determined key for the license. Cannot be used on encrypted licenses.

  • linksuspended

    boolean, optional, default isfalse

    Whether or not the license is suspended.

  • linkmetadata

    hash, optional

    Hash containing license metadata.

linkRelationships

  • linkpolicy

    hash, required

    The policy to implement for the license.

  • linkuser

    hash, optional

    The user the license is for. If ommitted, the license will be user-less. This is useful if you're managing users within your own database. If authenticated as a user, this relationship is required and must be the authenticated user.

Definition

POST https://api.keygen.sh/v1/accounts/<%= account %>/licenses \
  -d '{ "data": { "type": "licenses", "attributes": {DATA}, "relationships": {DATA} } }'

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/licenses", {
  method: "POST",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  },
  body: JSON.stringify({
    "data": {
      "type": "licenses",
      "relationships": {
        "policy": {
          "data": {
            "type": "policies",
            "id": "37b632f4-8e1e-4af9-8717-634765364628"
          }
        },
        "user": {
          "data": {
            "type": "users",
            "id": "015a33dd-3aca-43a9-8786-328042cce30a"
          }
        }
      }
    }
  })
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/licenses",
  method: .post,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ],
  parameters: [
    "data": [
      "type": "licenses",
      "relationships": [
        "policy": [
          "data": [
            "type": "policies",
            "id": "37b632f4-8e1e-4af9-8717-634765364628"
          ]
        ],
        "user": [
          "data": [
            "type": "users",
            "id": "015a33dd-3aca-43a9-8786-328042cce30a"
          ]
        ]
      ]
    ]
  ],
  encoding: JSONEncoding.default
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl -X POST https://api.keygen.sh/v1/accounts/<%= account %>/licenses \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>' \
  -d '{
        "data": {
          "type": "licenses",
          "relationships": {
            "policy": {
              "data": {
                "type": "policies",
                "id": "37b632f4-8e1e-4af9-8717-634765364628"
              }
            },
            "user": {
              "data": {
                "type": "users",
                "id": "015a33dd-3aca-43a9-8786-328042cce30a"
              }
            }
          }
        }
      }'

Example response / 201 Created

{
  "data": {
    "id": "b18e3f3a-330c-4d8d-ae2e-014db21fa827",
    "type": "licenses",
    "links": {
      "self": "/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827"
    },
    "attributes": {
      "key": "024e1ec7440f43b0b1ecc51c40897931-9fc2bb9d3cbd3d207fb713227737b637-1788b9572a82ce14166227a8d4db5b6d-904064d3432be2ab0088d60d09fca7v1",
      "expiry": "<%= expiry %>",
      "suspended": false,
      "encrypted": false,
      "lastCheckIn": null,
      "nextCheckIn": null,
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "product": {
        "links": {
          "related": "/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/product"
        },
        "data": {
          "type": "products",
          "id": "eb4e14a7-ea41-4ede-b3fe-5e835c17156b"
        }
      },
      "policy": {
        "links": {
          "related": "/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/policy"
        },
        "data": {
          "type": "policies",
          "id": "37b632f4-8e1e-4af9-8717-634765364628"
        }
      },
      "user": {
        "links": {
          "related": "/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/user"
        },
        "data": {
          "type": "users",
          "id": "015a33dd-3aca-43a9-8786-328042cce30a"
        }
      },
      "machines": {
        "links": {
          "related": "/v1/accounts/<%= account %>/machines?license=b18e3f3a-330c-4d8d-ae2e-014db21fa827"
        }
      }
    }
  }
}

linkRetrieve a license

Retrieves the details of an existing license.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to view the resource: either an admin, the product it belongs to, or the user it belongs to.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

  • linkid

    string, required

    The identifier of the license to be retrieved.

Definition

GET https://api.keygen.sh/v1/accounts/<%= account %>/licenses/{ID}

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/licenses/eef41cf5-f32e-4dab-a867-b9738d87285b", {
  method: "GET",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/licenses/eef41cf5-f32e-4dab-a867-b9738d87285b",
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl https://api.keygen.sh/v1/accounts/<%= account %>/licenses/eef41cf5-f32e-4dab-a867-b9738d87285b \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": {
    "id": "eef41cf5-f32e-4dab-a867-b9738d87285b",
    "type": "licenses",
    "links": {
      "self": "/v1/accounts/<%= account %>/licenses/eef41cf5-f32e-4dab-a867-b9738d87285b"
    },
    "attributes": {
      "expiry": "<%= expiry %>",
      "suspended": false,
      "encrypted": true,
      "lastCheckIn": null,
      "nextCheckIn": null,
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "product": {
        "links": {
          "related": "/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/product"
        },
        "data": {
          "type": "products",
          "id": "eb4e14a7-ea41-4ede-b3fe-5e835c17156b"
        }
      },
      "policy": {
        "links": {
          "related": "/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/policy"
        },
        "data": {
          "type": "policies",
          "id": "70af414d-6152-4ff1-892b-15a40ada6b4e"
        }
      },
      "user": {
        "links": {
          "related": "/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/user"
        },
        "data": {
          "type": "users",
          "id": "e8bf27c0-5f9c-4135-a65c-f52706c5fd4c"
        }
      },
      "machines": {
        "links": {
          "related": "/v1/accounts/<%= account %>/machines?license=eef41cf5-f32e-4dab-a867-b9738d87285b"
        }
      }
    }
  }
}

linkUpdate a license

Updates the specified license resource by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to manage the resource: either an admin or the product it belongs to.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

  • linkid

    string, required

    The identifier of the license to be updated.

linkAttributes

  • linkexpiry

    timestamp, optional

    When the license will expire.

  • linksuspended

    boolean, optional

    Whether or not the license is suspended.

  • linkmetadata

    hash, optionalprotected

    Hash containing license metadata.

Definition

PATCH https://api.keygen.sh/v1/accounts/<%= account %>/licenses/{ID} \
  -d '{ "data": { "type": "licenses", "attributes": {DATA} } }'

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827", {
  method: "PATCH",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  },
  body: JSON.stringify({
    "data": {
      "type": "licenses",
      "attributes": {
        "expiry": "2020-01-01T00:00:00.000Z"
      }
    }
  })
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827",
  method: .patch,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ],
  parameters: [
    "data": [
      "type": "licenses",
      "attributes": [
        "expiry": "2020-01-01T00:00:00.000Z"
      ]
    ]
  ],
  encoding: JSONEncoding.default
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl -X PATCH https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827 \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>' \
  -d '{
        "data": {
          "type": "licenses",
          "attributes": {
            "expiry": "2020-01-01T00:00:00.000Z"
          }
        }
      }'

Example response / 200 OK

{
  "data": {
    "id": "b18e3f3a-330c-4d8d-ae2e-014db21fa827",
    "type": "licenses",
    "links": {
      "self": "/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827"
    },
    "attributes": {
      "key": "024e1ec7440f43b0b1ecc51c40897931-9fc2bb9d3cbd3d207fb713227737b637-1788b9572a82ce14166227a8d4db5b6d-904064d3432be2ab0088d60d09fca7v1",
      "expiry": "2020-01-01T00:00:00.000Z",
      "suspended": false,
      "encrypted": false,
      "lastCheckIn": null,
      "nextCheckIn": null,
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= updated %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "product": {
        "links": {
          "related": "/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/product"
        },
        "data": {
          "type": "products",
          "id": "eb4e14a7-ea41-4ede-b3fe-5e835c17156b"
        }
      },
      "policy": {
        "links": {
          "related": "/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/policy"
        },
        "data": {
          "type": "policies",
          "id": "70af414d-6152-4ff1-892b-15a40ada6b4e"
        }
      },
      "user": {
        "links": {
          "related": "/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/user"
        },
        "data": {
          "type": "users",
          "id": "e8bf27c0-5f9c-4135-a65c-f52706c5fd4c"
        }
      },
      "machines": {
        "links": {
          "related": "/v1/accounts/<%= account %>/machines?license=b18e3f3a-330c-4d8d-ae2e-014db21fa827"
        }
      }
    }
  }
}

linkDelete a license

Permanently deletes a license. It cannot be undone. This action also immediately deletes any machines that the license is associated with.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to manage the resource: either an admin, the product it belongs to, or if the license's policy is unprotected, the user it belongs to.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

  • linkid

    string, required

    The identifier of the license to be deleted.

Definition

DELETE https://api.keygen.sh/v1/accounts/<%= account %>/licenses/{ID}

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/licenses/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065", {
  method: "DELETE",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/licenses/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065",
  method: .delete,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
    let status = response.response?.statusCode
}
curl -X DELETE https://api.keygen.sh/v1/accounts/<%= account %>/licenses/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065 \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 204 No Content

No content

linkList all licenses

Returns a list of licenses. The licenses are returned sorted by creation date, with the most recent licenses appearing first. Resources are automatically scoped to the authenticated bearer e.g. when authenticated as a user, only licenses of that specific user will be listed.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to view the resources.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

linkFilters

  • linklimit

    integer, default is10

    A limit on the number of licenses to be returned. Limit must be a number between 1 and 100.

    https://api.keygen.sh/v1/accounts/<%= account %>/licenses?limit=25

  • linkpage

    hash

    Hash containing page size and page number. Page size must be a number between 1 and 100

    https://api.keygen.sh/v1/accounts/<%= account %>/licenses?page[size]=15&page[number]=2

  • linksuspended

    boolean

    The suspended status of the license to filter by.

    https://api.keygen.sh/v1/accounts/<%= account %>/licenses?suspended=true

  • linkproduct

    string

    The identifier of the product to filter by.

    https://api.keygen.sh/v1/accounts/<%= account %>/licenses?product=3ab38aae-bbf7-4846-9c32-af9d94bf5ad4

  • linkpolicy

    string

    The identifier of the policy to filter by.

    https://api.keygen.sh/v1/accounts/<%= account %>/licenses?policy=0b4b1a9a-e25a-4f14-a95e-d9dd378d6065

  • linkuser

    string

    The identifier of the user to filter by.

    https://api.keygen.sh/v1/accounts/<%= account %>/licenses?user=a5a154d2-f026-40fa-bc8d-a7e3ca415298

Definition

GET https://api.keygen.sh/v1/accounts/<%= account %>/licenses{FILTERS}

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/licenses?limit=15", {
  method: "GET",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/licenses?limit=15",
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl https://api.keygen.sh/v1/accounts/<%= account %>/licenses?limit=15 -g \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": [
    {
      "id": "b18e3f3a-330c-4d8d-ae2e-014db21fa827",
      "type": "licenses",
      "links": {
        "self": "/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827"
      },
      "attributes": {
        "key": "024e1ec7440f43b0b1ecc51c40897931-9fc2bb9d3cbd3d207fb713227737b637-1788b9572a82ce14166227a8d4db5b6d-904064d3432be2ab0088d60d09fca7v1",
        "expiry": "<%= expiry %>",
        "suspended": false,
        "encrypted": false,
        "lastCheckIn": null,
        "nextCheckIn": null,
        "metadata": {},
        "created": "<%= created %>",
        "updated": "<%= created %>"
      },
      "relationships": {
        "account": {
          "links": {
            "related": "/v1/accounts/<%= account %>"
          },
          "data": {
            "type": "accounts",
            "id": "<%= account %>"
          }
        },
        "product": {
          "links": {
            "related": "/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/product"
          },
          "data": {
            "type": "products",
            "id": "eb4e14a7-ea41-4ede-b3fe-5e835c17156b"
          }
        },
        "policy": {
          "links": {
            "related": "/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/policy"
          },
          "data": {
            "type": "policies",
            "id": "37b632f4-8e1e-4af9-8717-634765364628"
          }
        },
        "user": {
          "links": {
            "related": "/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/user"
          },
          "data": {
            "type": "users",
            "id": "015a33dd-3aca-43a9-8786-328042cce30a"
          }
        },
        "machines": {
          "links": {
            "related": "/v1/accounts/<%= account %>/machines?license=b18e3f3a-330c-4d8d-ae2e-014db21fa827"
          }
        }
      }
    },
    …
  ]
}

linkLicense actions

Actions for the license resource.

linkValidate license

Action to validate a license. This will check the following: if the license is suspended, if the license is expired, if the license is overdue for check-in, and if the license meets its machine requirements (if strict).

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to validate the resource: either an admin, the product it belongs to, or the user it belongs to.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

  • linkid

    string, required

    The identifier of the license to validate.

Definition

GET https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/validate

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/validate", {
  method: "GET",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})

const { meta, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/validate",
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/validate \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "meta": {
    "valid": true,
    "detail": "is valid"
  }
}

linkValidate key

Action to validate a license key. This will look up the license by its key and check the following: if the license is suspended, if the license is expired, if the license is overdue for check-in, and if the license meets its machine requirements (if strict).

linkAuthentication

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

linkMeta

  • linkkey

    string, required

    The license key to validate.

  • linkencrypted

    boolean, optional, default isfalse

    Whether the license implements an encrypted policy. Encrypted licenses will fail validation unless this is specified.

Definition

POST https://api.keygen.sh/v1/accounts/<%= account %>/licenses/actions/validate-key \
  -d '{ "meta": {DATA} }'

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/licenses/actions/validate-key", {
  method: "POST",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json"
  },
  body: JSON.stringify({
    "meta": {
      "key": "B8A5-91D7-CB9A-DAE4-4F6E-1128"
    }
  })
})

const { meta, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/licenses/actions/validate-key",
  method: .post,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json"
  ],
  parameters: [
    "meta": [
      "key": "B8A5-91D7-CB9A-DAE4-4F6E-1128"
    ]
  ],
  encoding: JSONEncoding.default
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl -X POST https://api.keygen.sh/v1/accounts/<%= account %>/licenses/actions/validate-key \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -d '{
        "meta": {
          "key": "B8A5-91D7-CB9A-DAE4-4F6E-1128"
        }
      }'

Example response / 200 OK

{
  "meta": {
    "valid": false,
    "detail": "is expired"
  }
}

linkSuspend license

Action to temporarily suspend (ban) a license. This will cause the license to fail validation until reinistated. To permanently revoke a license, see the revoke action.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to suspend the resource: either an admin or the product it belongs to.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

  • linkid

    string, required

    The identifier of the license to suspend.

Definition

POST https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/suspend

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/suspend", {
  method: "POST",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/suspend",
  method: .post,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl -X POST https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/suspend \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": {
    "id": "b18e3f3a-330c-4d8d-ae2e-014db21fa827",
    "type": "licenses",
    "links": {
      "self": "/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827"
    },
    "attributes": {
      "key": "024e1ec7440f43b0b1ecc51c40897931-9fc2bb9d3cbd3d207fb713227737b637-1788b9572a82ce14166227a8d4db5b6d-904064d3432be2ab0088d60d09fca7v1",
      "expiry": "2020-01-01T00:00:00.000Z",
      "suspended": true,
      "encrypted": false,
      "lastCheckIn": null,
      "nextCheckIn": null,
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= updated %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "product": {
        "links": {
          "related": "/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/product"
        },
        "data": {
          "type": "products",
          "id": "eb4e14a7-ea41-4ede-b3fe-5e835c17156b"
        }
      },
      "policy": {
        "links": {
          "related": "/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/policy"
        },
        "data": {
          "type": "policies",
          "id": "70af414d-6152-4ff1-892b-15a40ada6b4e"
        }
      },
      "user": {
        "links": {
          "related": "/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/user"
        },
        "data": {
          "type": "users",
          "id": "e8bf27c0-5f9c-4135-a65c-f52706c5fd4c"
        }
      },
      "machines": {
        "links": {
          "related": "/v1/accounts/<%= account %>/machines?license=b18e3f3a-330c-4d8d-ae2e-014db21fa827"
        }
      }
    }
  }
}

linkReinstate license

Action to reinstate a suspended license.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to reinstate the resource: either an admin or the product it belongs to.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

  • linkid

    string, required

    The identifier of the license to reinstate.

Definition

POST https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/reinstate

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/reinstate", {
  method: "POST",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/reinstate",
  method: .post,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl -X POST https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/reinstate \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": {
    "id": "b18e3f3a-330c-4d8d-ae2e-014db21fa827",
    "type": "licenses",
    "links": {
      "self": "/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827"
    },
    "attributes": {
      "key": "024e1ec7440f43b0b1ecc51c40897931-9fc2bb9d3cbd3d207fb713227737b637-1788b9572a82ce14166227a8d4db5b6d-904064d3432be2ab0088d60d09fca7v1",
      "expiry": "2020-01-01T00:00:00.000Z",
      "suspended": false,
      "encrypted": false,
      "lastCheckIn": null,
      "nextCheckIn": null,
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= updated %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "product": {
        "links": {
          "related": "/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/product"
        },
        "data": {
          "type": "products",
          "id": "eb4e14a7-ea41-4ede-b3fe-5e835c17156b"
        }
      },
      "policy": {
        "links": {
          "related": "/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/policy"
        },
        "data": {
          "type": "policies",
          "id": "70af414d-6152-4ff1-892b-15a40ada6b4e"
        }
      },
      "user": {
        "links": {
          "related": "/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/user"
        },
        "data": {
          "type": "users",
          "id": "e8bf27c0-5f9c-4135-a65c-f52706c5fd4c"
        }
      },
      "machines": {
        "links": {
          "related": "/v1/accounts/<%= account %>/machines?license=b18e3f3a-330c-4d8d-ae2e-014db21fa827"
        }
      }
    }
  }
}

linkRenew license

Action to renew a license. Extends license expiry by the policy's duration.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to renew the resource: either an admin, the product it belongs to, or if the license's policy is unprotected, the user it belongs to.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

  • linkid

    string, required

    The identifier of the license to renew.

Definition

POST https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/renew

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/renew", {
  method: "POST",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/renew",
  method: .post,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl -X POST https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/renew \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": {
    "id": "b18e3f3a-330c-4d8d-ae2e-014db21fa827",
    "type": "licenses",
    "links": {
      "self": "/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827"
    },
    "attributes": {
      "key": "024e1ec7440f43b0b1ecc51c40897931-9fc2bb9d3cbd3d207fb713227737b637-1788b9572a82ce14166227a8d4db5b6d-904064d3432be2ab0088d60d09fca7v1",
      "expiry": "2020-01-01T00:00:00.000Z",
      "suspended": false,
      "encrypted": false,
      "lastCheckIn": null,
      "nextCheckIn": null,
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= updated %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "product": {
        "links": {
          "related": "/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/product"
        },
        "data": {
          "type": "products",
          "id": "eb4e14a7-ea41-4ede-b3fe-5e835c17156b"
        }
      },
      "policy": {
        "links": {
          "related": "/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/policy"
        },
        "data": {
          "type": "policies",
          "id": "70af414d-6152-4ff1-892b-15a40ada6b4e"
        }
      },
      "user": {
        "links": {
          "related": "/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/user"
        },
        "data": {
          "type": "users",
          "id": "e8bf27c0-5f9c-4135-a65c-f52706c5fd4c"
        }
      },
      "machines": {
        "links": {
          "related": "/v1/accounts/<%= account %>/machines?license=b18e3f3a-330c-4d8d-ae2e-014db21fa827"
        }
      }
    }
  }
}

linkRevoke license

Action to revoke (delete) a license. This cannot be undone. This action also immediately deletes any machines that the license is associated with.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to revoke the resource: either an admin, the product it belongs to, or if the license's policy is unprotected, the user it belongs to.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

  • linkid

    string, required

    The identifier of the license to revoke.

Definition

DELETE https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/revoke

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/revoke", {
  method: "DELETE",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/revoke",
  method: .delete,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let status = response.response?.statusCode
}
curl -X DELETE https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/revoke \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 204 No Content

No content

linkCheck-In license

Action to check-in a license. Sets the license's lastCheckIn to the current time, and the license's nextCheckIn according to the policy's check-in interval.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to check-in the resource: either an admin, the product it belongs to, or if the license's policy is unprotected, the user it belongs to.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

  • linkid

    string, required

    The identifier of the license to check-in.

Definition

POST https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/check-in

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/check-in", {
  method: "POST",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/check-in",
  method: .post,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl -X POST https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/check-in \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": {
    "id": "b18e3f3a-330c-4d8d-ae2e-014db21fa827",
    "type": "licenses",
    "links": {
      "self": "/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827"
    },
    "attributes": {
      "key": "024e1ec7440f43b0b1ecc51c40897931-9fc2bb9d3cbd3d207fb713227737b637-1788b9572a82ce14166227a8d4db5b6d-904064d3432be2ab0088d60d09fca7v1",
      "expiry": "2020-01-01T00:00:00.000Z",
      "suspended": false,
      "encrypted": false,
      "lastCheckIn": "<%= lastCheckIn %>",
      "nextCheckIn": "<%= nextCheckIn %>",
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= updated %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "product": {
        "links": {
          "related": "/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/product"
        },
        "data": {
          "type": "products",
          "id": "eb4e14a7-ea41-4ede-b3fe-5e835c17156b"
        }
      },
      "policy": {
        "links": {
          "related": "/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/policy"
        },
        "data": {
          "type": "policies",
          "id": "70af414d-6152-4ff1-892b-15a40ada6b4e"
        }
      },
      "user": {
        "links": {
          "related": "/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/user"
        },
        "data": {
          "type": "users",
          "id": "e8bf27c0-5f9c-4135-a65c-f52706c5fd4c"
        }
      },
      "machines": {
        "links": {
          "related": "/v1/accounts/<%= account %>/machines?license=b18e3f3a-330c-4d8d-ae2e-014db21fa827"
        }
      }
    }
  }
}

linkMachines

linkThe machine object

Below you will find the various attributes for the machine resource, as well as the machine resource's relationships. Machines can be used to track and manage where your users are allowed to use your product.

linkAttributes

  • linkfingerprint

    string

    The fingerprint of the machine. This can be an arbitrary string, but must be unique within the scope of the license it belongs to.

  • linkname

    string

    The human-readable name of the machine.

  • linkip

    string

    The IP of the machine.

  • linkhostname

    string

    The hostname of the machine.

  • linkplatform

    string

    The platform of the machine.

  • linkmetadata

    hash

    Hash containing machine metadata.

  • linkcreated

    timestampread only

    When the machine was created.

  • linkupdated

    timestampread only

    When the machine was last updated.

linkRelationships

  • linkaccount

    individual

    The account that the machine belongs to.

  • linkproduct

    individual

    The product that the machine is associated with.

  • linklicense

    individual

    The license that the machine is associated with.

  • linkuser

    individual

    The user that owns the machine.

Example object

{
  "data": {
    "id": "9c4c90c8-d4d3-4571-9363-4c7b0332a6a4",
    "type": "machines",
    "links": {
      "self": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4"
    },
    "attributes": {
      "fingerprint": "4d:Eq:UV:D3:XZ:tL:WN:Bz:mA:Eg:E6:Mk:YX:dK:NC",
      "ip": null,
      "hostname": null,
      "platform": "macOS",
      "name": "Office MacBook Pro",
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "product": {
        "links": {
          "related": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/product"
        },
        "data": {
          "type": "products",
          "id": "22b78db6-6a2e-4a7f-9369-157976148c4c"
        }
      },
      "license": {
        "links": {
          "related": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/license"
        },
        "data": {
          "type": "licenses",
          "id": "4097d726-6cc5-4156-8575-3a96387e19b4"
        }
      },
      "user": {
        "links": {
          "related": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/user"
        },
        "data": {
          "type": "users",
          "id": "15ad7012-b570-48b7-88c1-fbab68be9d05"
        }
      }
    }
  }
}

linkCreate a machine

Creates a new machine resource.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to create the resource: either an admin, the product it belongs to, or the user it belongs to.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

linkAttributes

  • linkfingerprint

    string, required

    The fingerprint of the machine. This can be an arbitrary string, but must be unique within the scope of the license it belongs to.

  • linkname

    string, optional

    The human-readable name of the machine.

  • linkip

    string, optional

    The IP of the machine.

  • linkhostname

    string, optional

    The hostname of the machine.

  • linkplatform

    string, optional

    The platform of the machine.

  • linkmetadata

    hash, optional

    Hash containing machine metadata.

linkRelationships

  • linklicense

    hash, required

    The license the machine is for.

Definition

POST https://api.keygen.sh/v1/accounts/<%= account %>/machines \
  -d '{ "data": { "type": "machines", "attributes": {DATA}, "relationships": {DATA} } }'

Example request

const fetch = require("node-fetch")
const sha1 = require("sha1")
const { promisify } = require("bluebird")
const { getMac } = require("getmac")

const getMacAddress = promisify(getMac)
const fingerprint = (platform, macAddress) => {
  return sha1(platform + macAddress /* + anything else you want to use */)
           .split(/(.{2})/)
           .filter(Boolean)
           .join(":")
}

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/machines", {
  method: "POST",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  },
  body: JSON.stringify({
    "data": {
      "type": "machines",
      "attributes": {
        "fingerprint": fingerprint(process.platform, await getMacAddress()),
        "platform": "macOS",
        "name": "Office MacBook Pro"
      },
      "relationships": {
        "license": {
          "data": {
            "type": "licenses",
            "id": "4097d726-6cc5-4156-8575-3a96387e19b4"
          }
        }
      }
    }
  })
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/machines",
  method: .post,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ],
  parameters: [
    "data": [
      "type": "machines",
      "attributes": [
        "fingerprint": "4d:Eq:UV:D3:XZ:tL:WN:Bz:mA:Eg:E6:Mk:YX:dK:NC",
        "platform": "macOS",
        "name": "Office MacBook Pro"
      ],
      "relationships": [
        "license": [
          "data": [
            "type": "licenses",
            "id": "4097d726-6cc5-4156-8575-3a96387e19b4"
          ]
        ]
      ]
    ]
  ],
  encoding: JSONEncoding.default
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl -X POST https://api.keygen.sh/v1/accounts/<%= account %>/machines \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>' \
  -d '{
        "data": {
          "type": "machines",
          "attributes": {
            "fingerprint": "4d:Eq:UV:D3:XZ:tL:WN:Bz:mA:Eg:E6:Mk:YX:dK:NC",
            "platform": "macOS",
            "name": "Office MacBook Pro"
          },
          "relationships": {
            "license": {
              "data": {
                "type": "licenses",
                "id": "4097d726-6cc5-4156-8575-3a96387e19b4"
              }
            }
          }
        }
      }'

Example response / 201 Created

{
  "data": {
    "id": "9c4c90c8-d4d3-4571-9363-4c7b0332a6a4",
    "type": "machines",
    "links": {
      "self": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4"
    },
    "attributes": {
      "fingerprint": "4d:Eq:UV:D3:XZ:tL:WN:Bz:mA:Eg:E6:Mk:YX:dK:NC",
      "ip": null,
      "hostname": null,
      "platform": "macOS",
      "name": "Office MacBook Pro",
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "product": {
        "links": {
          "related": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/product"
        },
        "data": {
          "type": "products",
          "id": "22b78db6-6a2e-4a7f-9369-157976148c4c"
        }
      },
      "license": {
        "links": {
          "related": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/license"
        },
        "data": {
          "type": "licenses",
          "id": "4097d726-6cc5-4156-8575-3a96387e19b4"
        }
      },
      "user": {
        "links": {
          "related": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/user"
        },
        "data": {
          "type": "users",
          "id": "15ad7012-b570-48b7-88c1-fbab68be9d05"
        }
      }
    }
  }
}

linkRetrieve a machine

Retrieves the details of an existing machine.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to view the resource: either an admin, the product it belongs to, or the user it belongs to.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

  • linkid

    string, required

    The identifier of the machine to be retrieved.

Definition

GET https://api.keygen.sh/v1/accounts/<%= account %>/machines/{ID}

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/machines/eef41cf5-f32e-4dab-a867-b9738d87285b", {
  method: "GET",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/machines/eef41cf5-f32e-4dab-a867-b9738d87285b",
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl https://api.keygen.sh/v1/accounts/<%= account %>/machines/eef41cf5-f32e-4dab-a867-b9738d87285b \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": {
    "id": "9c4c90c8-d4d3-4571-9363-4c7b0332a6a4",
    "type": "machines",
    "links": {
      "self": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4"
    },
    "attributes": {
      "fingerprint": "4d:Eq:UV:D3:XZ:tL:WN:Bz:mA:Eg:E6:Mk:YX:dK:NC",
      "ip": null,
      "hostname": null,
      "platform": "macOS",
      "name": "Office MacBook Pro",
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "product": {
        "links": {
          "related": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/product"
        },
        "data": {
          "type": "products",
          "id": "22b78db6-6a2e-4a7f-9369-157976148c4c"
        }
      },
      "license": {
        "links": {
          "related": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/license"
        },
        "data": {
          "type": "licenses",
          "id": "4097d726-6cc5-4156-8575-3a96387e19b4"
        }
      },
      "user": {
        "links": {
          "related": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/user"
        },
        "data": {
          "type": "users",
          "id": "15ad7012-b570-48b7-88c1-fbab68be9d05"
        }
      }
    }
  }
}

linkUpdate a machine

Updates the specified machine resource by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to manage the resource: either an admin, the product it belongs to, or the user it belongs to.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

  • linkid

    string, required

    The identifier of the machine to be updated.

linkAttributes

  • linkname

    string, optional

    The human-readable name of the machine.

  • linkip

    string, optional

    The IP of the machine.

  • linkhostname

    string, optional

    The hostname of the machine.

  • linkplatform

    string, optional

    The platform of the machine.

  • linkmetadata

    hash, optionalprotected

    Hash containing machine metadata.

Definition

PATCH https://api.keygen.sh/v1/accounts/<%= account %>/machines/{ID} \
  -d '{ "data": { "type": "machines", "attributes": {DATA} } }'

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/machines/b18e3f3a-330c-4d8d-ae2e-014db21fa827", {
  method: "PATCH",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  },
  body: JSON.stringify({
    "data": {
      "type": "machines",
      "attributes": {
        "ip": "192.168.1.1"
      }
    }
  })
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/machines/b18e3f3a-330c-4d8d-ae2e-014db21fa827",
  method: .patch,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ],
  parameters: [
    "data": [
      "type": "machines",
      "attributes": [
        "ip": "192.168.1.1"
      ]
    ]
  ],
  encoding: JSONEncoding.default
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl -X PATCH https://api.keygen.sh/v1/accounts/<%= account %>/machines/b18e3f3a-330c-4d8d-ae2e-014db21fa827 \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>' \
  -d '{
        "data": {
          "type": "machines",
          "attributes": {
            "ip": "192.168.1.1"
          }
        }
      }'

Example response / 200 OK

{
  "data": {
    "id": "9c4c90c8-d4d3-4571-9363-4c7b0332a6a4",
    "type": "machines",
    "links": {
      "self": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4"
    },
    "attributes": {
      "fingerprint": "4d:Eq:UV:D3:XZ:tL:WN:Bz:mA:Eg:E6:Mk:YX:dK:NC",
      "ip": "192.168.1.1",
      "hostname": null,
      "platform": "macOS",
      "name": "Office MacBook Pro",
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= updated %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "product": {
        "links": {
          "related": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/product"
        },
        "data": {
          "type": "products",
          "id": "22b78db6-6a2e-4a7f-9369-157976148c4c"
        }
      },
      "license": {
        "links": {
          "related": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/license"
        },
        "data": {
          "type": "licenses",
          "id": "4097d726-6cc5-4156-8575-3a96387e19b4"
        }
      },
      "user": {
        "links": {
          "related": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/user"
        },
        "data": {
          "type": "users",
          "id": "15ad7012-b570-48b7-88c1-fbab68be9d05"
        }
      }
    }
  }
}

linkDelete a machine

Permanently deletes a machine. It cannot be undone.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to manage the resource: either an admin, the product it belongs to, or the user it belongs to.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

  • linkid

    string, required

    The identifier of the machine to be deleted.

Definition

DELETE https://api.keygen.sh/v1/accounts/<%= account %>/machines/{ID}

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4", {
  method: "DELETE",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4",
  method: .delete,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let status = response.response?.statusCode
}
curl -X DELETE https://api.keygen.sh/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4 \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 204 No Content

No content

linkList all machines

Returns a list of machines. The machines are returned sorted by creation date, with the most recent machines appearing first. Resources are automatically scoped to the authenticated bearer e.g. when authenticated as a user, only machines of that specific user will be listed.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to view the resources.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

linkFilters

  • linklimit

    integer, default is10

    A limit on the number of machines to be returned. Limit must be a number between 1 and 100.

    https://api.keygen.sh/v1/accounts/<%= account %>/machines?limit=25

  • linkpage

    hash

    Hash containing page size and page number. Page size must be a number between 1 and 100

    https://api.keygen.sh/v1/accounts/<%= account %>/machines?page[size]=15&page[number]=2

  • linkfingerprint

    string

    The machine fingerprint to filter by.

    https://api.keygen.sh/v1/accounts/<%= account %>/machines?fingerprint=4d:Eq:UV:D3:XZ:tL:WN:Bz:mA:Eg:E6:Mk:YX:dK:NC

  • linkproduct

    string

    The identifier of the product to filter by.

    https://api.keygen.sh/v1/accounts/<%= account %>/machines?product=3ab38aae-bbf7-4846-9c32-af9d94bf5ad4

  • linklicense

    string

    The identifier of the license to filter by.

    https://api.keygen.sh/v1/accounts/<%= account %>/machines?license=3fd7ff1c-e778-4030-a81c-d2242d909258

  • linkuser

    string

    The identifier of the user to filter by.

    https://api.keygen.sh/v1/accounts/<%= account %>/machines?user=a5a154d2-f026-40fa-bc8d-a7e3ca415298

Definition

GET https://api.keygen.sh/v1/accounts/<%= account %>/machines{FILTERS}

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/machines?limit=15", {
  method: "GET",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/machines?limit=15",
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl https://api.keygen.sh/v1/accounts/<%= account %>/machines?limit=15 -g \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": [
    {
      "id": "9c4c90c8-d4d3-4571-9363-4c7b0332a6a4",
      "type": "machines",
      "links": {
        "self": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4"
      },
      "attributes": {
        "fingerprint": "4d:Eq:UV:D3:XZ:tL:WN:Bz:mA:Eg:E6:Mk:YX:dK:NC",
        "ip": null,
        "hostname": null,
        "platform": "macOS",
        "name": "Office MacBook Pro",
        "metadata": {},
        "created": "<%= created %>",
        "updated": "<%= created %>"
      },
      "relationships": {
        "account": {
          "links": {
            "related": "/v1/accounts/<%= account %>"
          },
          "data": {
            "type": "accounts",
            "id": "<%= account %>"
          }
        },
        "product": {
          "links": {
            "related": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/product"
          },
          "data": {
            "type": "products",
            "id": "22b78db6-6a2e-4a7f-9369-157976148c4c"
          }
        },
        "license": {
          "links": {
            "related": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/license"
          },
          "data": {
            "type": "licenses",
            "id": "4097d726-6cc5-4156-8575-3a96387e19b4"
          }
        },
        "user": {
          "links": {
            "related": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/user"
          },
          "data": {
            "type": "users",
            "id": "15ad7012-b570-48b7-88c1-fbab68be9d05"
          }
        }
      }
    },
    …
  ]
}

linkKeys

linkThe key object

Below you will find the various attributes for the key resource, as well as the key resource's relationships.

These are unused keys within a policy's pool – they are not valid licenses. These are used when creating new licenses for a pooled policy or when using a pool's pop action.

linkAttributes

  • linkkey

    string

    The unique key string for the key.

  • linkcreated

    timestampread only

    When the key was created.

  • linkupdated

    timestampread only

    When the key was last updated.

linkRelationships

  • linkaccount

    individual

    The account that the key belongs to.

  • linkproduct

    individual

    The product that the key is associated with.

  • linkpolicy

    individual

    The pooled policy that the key belongs to.

Example object

{
  "data": {
    "id": "6e936a61-94ad-44d1-88ac-88da9f10eca7",
    "type": "keys",
    "links": {
      "self": "/v1/accounts/<%= account %>/keys/6e936a61-94ad-44d1-88ac-88da9f10eca7"
    },
    "attributes": {
      "key": "B8A5-91D7-CB9A-DAE4-4F6E-1128",
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "product": {
        "links": {
          "related": "/v1/accounts/<%= account %>/keys/6e936a61-94ad-44d1-88ac-88da9f10eca7/product"
        },
        "data": {
          "type": "products",
          "id": "1f286fb6-c9bb-498b-a4e7-6c67748b1f4f"
        }
      },
      "policy": {
        "links": {
          "related": "/v1/accounts/<%= account %>/keys/6e936a61-94ad-44d1-88ac-88da9f10eca7/policy"
        },
        "data": {
          "type": "policies",
          "id": "95981290-518b-4109-a611-c0001214b3c5"
        }
      }
    }
  }
}

linkCreate a key

Creates a new key resource.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to create the resource: either an admin or the product it belongs to.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

linkAttributes

  • linkkey

    string, required

    The unique key string for the key. The key cannot collide with license keys that already exist.

linkRelationships

  • linkpolicy

    hash, required

    The pooled policy the key belongs to.

Definition

POST https://api.keygen.sh/v1/accounts/<%= account %>/keys \
  -d '{ "data": { "type": "keys", "attributes": {DATA}, "relationships": {DATA} } }'

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/keys", {
  method: "POST",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  },
  body: JSON.stringify({
    "data": {
      "type": "keys",
      "attributes": {
        "key": "B8A5-91D7-CB9A-DAE4-4F6E-1128"
      },
      "relationships": {
        "policy": {
          "data": {
            "type": "policies",
            "id": "4ba02145-d1e7-4443-8104-dd1e4236d869"
          }
        }
      }
    }
  })
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/keys",
  method: .post,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ],
  parameters: [
    "data": [
      "type": "keys",
      "attributes": [
        "key": "B8A5-91D7-CB9A-DAE4-4F6E-1128"
      ],
      "relationships": [
        "policy": [
          "data": [
            "type": "policies",
            "id": "4ba02145-d1e7-4443-8104-dd1e4236d869"
          ]
        ]
      ]
    ]
  ],
  encoding: JSONEncoding.default
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl -X POST https://api.keygen.sh/v1/accounts/<%= account %>/keys \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>' \
  -d '{
        "data": {
          "type": "keys",
          "attributes": {
            "key": "B8A5-91D7-CB9A-DAE4-4F6E-1128"
          },
          "relationships": {
            "policy": {
              "data": {
                "type": "policies",
                "id": "4ba02145-d1e7-4443-8104-dd1e4236d869"
              }
            }
          }
        }
      }'

Example response / 201 Created

{
  "data": {
    "id": "6e936a61-94ad-44d1-88ac-88da9f10eca7",
    "type": "keys",
    "links": {
      "self": "/v1/accounts/<%= account %>/keys/6e936a61-94ad-44d1-88ac-88da9f10eca7"
    },
    "attributes": {
      "key": "B8A5-91D7-CB9A-DAE4-4F6E-1128",
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "product": {
        "links": {
          "related": "/v1/accounts/<%= account %>/keys/6e936a61-94ad-44d1-88ac-88da9f10eca7/product"
        },
        "data": {
          "type": "products",
          "id": "1f286fb6-c9bb-498b-a4e7-6c67748b1f4f"
        }
      },
      "policy": {
        "links": {
          "related": "/v1/accounts/<%= account %>/keys/6e936a61-94ad-44d1-88ac-88da9f10eca7/policy"
        },
        "data": {
          "type": "policies",
          "id": "4ba02145-d1e7-4443-8104-dd1e4236d869"
        }
      }
    }
  }
}

linkRetrieve a key

Retrieves the details of an existing key.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to view the resource: either an admin or the product it belongs to.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

  • linkid

    string, required

    The identifier of the key to be retrieved.

Definition

GET https://api.keygen.sh/v1/accounts/<%= account %>/keys/{ID}

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/keys/6e936a61-94ad-44d1-88ac-88da9f10eca7", {
  method: "GET",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/keys/6e936a61-94ad-44d1-88ac-88da9f10eca7",
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl https://api.keygen.sh/v1/accounts/<%= account %>/keys/6e936a61-94ad-44d1-88ac-88da9f10eca7 \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": {
    "id": "6e936a61-94ad-44d1-88ac-88da9f10eca7",
    "type": "keys",
    "links": {
      "self": "/v1/accounts/<%= account %>/keys/6e936a61-94ad-44d1-88ac-88da9f10eca7"
    },
    "attributes": {
      "key": "B8A5-91D7-CB9A-DAE4-4F6E-1128",
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "product": {
        "links": {
          "related": "/v1/accounts/<%= account %>/keys/6e936a61-94ad-44d1-88ac-88da9f10eca7/product"
        },
        "data": {
          "type": "products",
          "id": "1f286fb6-c9bb-498b-a4e7-6c67748b1f4f"
        }
      },
      "policy": {
        "links": {
          "related": "/v1/accounts/<%= account %>/keys/6e936a61-94ad-44d1-88ac-88da9f10eca7/policy"
        },
        "data": {
          "type": "policies",
          "id": "95981290-518b-4109-a611-c0001214b3c5"
        }
      }
    }
  }
}

linkUpdate a key

Updates the specified key resource by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to manage the resource: either an admin or the product it belongs to.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

  • linkid

    string, required

    The identifier of the key to be updated.

linkAttributes

  • linkkey

    string, optional

    The unique key string for the key.

Definition

PATCH https://api.keygen.sh/v1/accounts/<%= account %>/keys/{ID} \
  -d '{ "data": { "type": "keys", "attributes": {DATA} } }'

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/keys/b18e3f3a-330c-4d8d-ae2e-014db21fa827", {
  method: "PATCH",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  },
  body: JSON.stringify({
    "data": {
      "type": "keys",
      "attributes": {
        "key": "9adce-26df1-9c487-nb293-d0279"
      }
    }
  })
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/keys/b18e3f3a-330c-4d8d-ae2e-014db21fa827",
  method: .patch,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ],
  parameters: [
    "data": [
      "type": "keys",
      "attributes": [
        "key": "9adce-26df1-9c487-nb293-d0279"
      ]
    ]
  ],
  encoding: JSONEncoding.default
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl -X PATCH https://api.keygen.sh/v1/accounts/<%= account %>/keys/b18e3f3a-330c-4d8d-ae2e-014db21fa827 \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>' \
  -d '{
        "data": {
          "type": "keys",
          "attributes": {
            "key": "9adce-26df1-9c487-nb293-d0279"
          }
        }
      }'

Example response / 200 OK

{
  "data": {
    "id": "6e936a61-94ad-44d1-88ac-88da9f10eca7",
    "type": "keys",
    "links": {
      "self": "/v1/accounts/<%= account %>/keys/6e936a61-94ad-44d1-88ac-88da9f10eca7"
    },
    "attributes": {
      "key": "9adce-26df1-9c487-nb293-d0279",
      "created": "<%= created %>",
      "updated": "<%= updated %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "product": {
        "links": {
          "related": "/v1/accounts/<%= account %>/keys/6e936a61-94ad-44d1-88ac-88da9f10eca7/product"
        },
        "data": {
          "type": "products",
          "id": "1f286fb6-c9bb-498b-a4e7-6c67748b1f4f"
        }
      },
      "policy": {
        "links": {
          "related": "/v1/accounts/<%= account %>/keys/6e936a61-94ad-44d1-88ac-88da9f10eca7/policy"
        },
        "data": {
          "type": "policies",
          "id": "95981290-518b-4109-a611-c0001214b3c5"
        }
      }
    }
  }
}

linkDelete a key

Permanently deletes a key. It cannot be undone.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to manage the resource: either an admin or the product it belongs to.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

  • linkid

    string, required

    The identifier of the key to be deleted.

Definition

DELETE https://api.keygen.sh/v1/accounts/<%= account %>/keys/{ID}

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/keys/6e936a61-94ad-44d1-88ac-88da9f10eca7", {
  method: "DELETE",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/keys/6e936a61-94ad-44d1-88ac-88da9f10eca7",
  method: .delete,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let status = response.response?.statusCode
}
curl -X DELETE https://api.keygen.sh/v1/accounts/<%= account %>/keys/6e936a61-94ad-44d1-88ac-88da9f10eca7 \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 204 No Content

No content

linkList all keys

Returns a list of keys. The keys are returned sorted by creation date, with the most recent keys appearing first. Resources are automatically scoped to the authenticated bearer e.g. when authenticated as a product, only keys of that specific product will be listed.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to view the resources: either an admin or the product it belongs to.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

linkFilters

  • linklimit

    integer, default is10

    A limit on the number of keys to be returned. Limit must be a number between 1 and 100.

    https://api.keygen.sh/v1/accounts/<%= account %>/keys?limit=25

  • linkpage

    hash

    Hash containing page size and page number. Page size must be a number between 1 and 100

    https://api.keygen.sh/v1/accounts/<%= account %>/keys?page[size]=15&page[number]=2

  • linkproduct

    string

    The identifier of the product to filter by.

    https://api.keygen.sh/v1/accounts/<%= account %>/keys?product=3ab38aae-bbf7-4846-9c32-af9d94bf5ad4

  • linkpolicy

    string

    The identifier of the policy to filter by.

    https://api.keygen.sh/v1/accounts/<%= account %>/keys?policy=92ec8aa5-8f93-4e46-b356-4e54c16647be

Definition

GET https://api.keygen.sh/v1/accounts/<%= account %>/keys{FILTERS}

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/keys?limit=15", {
  method: "GET",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/keys?limit=15",
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl https://api.keygen.sh/v1/accounts/<%= account %>/keys?limit=15 -g \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": [
    {
      "id": "6e936a61-94ad-44d1-88ac-88da9f10eca7",
      "type": "keys",
      "links": {
        "self": "/v1/accounts/<%= account %>/keys/6e936a61-94ad-44d1-88ac-88da9f10eca7"
      },
      "attributes": {
        "key": "B8A5-91D7-CB9A-DAE4-4F6E-1128",
        "created": "<%= created %>",
        "updated": "<%= created %>"
      },
      "relationships": {
        "account": {
          "links": {
            "related": "/v1/accounts/<%= account %>"
          },
          "data": {
            "type": "accounts",
            "id": "<%= account %>"
          }
        },
        "product": {
          "links": {
            "related": "/v1/accounts/<%= account %>/keys/6e936a61-94ad-44d1-88ac-88da9f10eca7/product"
          },
          "data": {
            "type": "products",
            "id": "1f286fb6-c9bb-498b-a4e7-6c67748b1f4f"
          }
        },
        "policy": {
          "links": {
            "related": "/v1/accounts/<%= account %>/keys/6e936a61-94ad-44d1-88ac-88da9f10eca7/policy"
          },
          "data": {
            "type": "policies",
            "id": "95981290-518b-4109-a611-c0001214b3c5"
          }
        }
      }
    },
    …
  ]
}

linkWebhooks

Webhook events are dispatched using POST requests to an account's webhook endpoints. Events usually get sent quickly, but sometimes there can be a small delay. If you experience a delay longer than 1 hour for the initial event, please contact us.

Webhooks are asynchronous events. We do our best to always send them in a timely manner, but we DO NOT recommend relying on webhooks for events that are time-sensitive.

linkEvent Types

The following events are dispatched to all endpoints with a POST request containing an event object.

NOTE: Events that occur on "sub" resources like account.plan do not trigger the parent's update event. In addition, resource deletion e.g. policy.deleted or user.deleted events will not trigger "cascading" deletion events on dependent associations.
Event Payload
account.updated When your account is updated The updated account object
account.subscription.paused When your account's subscription is paused The updated account object
account.subscription.resumed When your account's subscription is resumed The updated account object
account.subscription.canceled When your account's subscription is canceled The updated account object
account.subscription.renewed When your account's subscription is renewed The updated account object
account.plan.updated When your account's plan is updated The updated plan object
account.billing.updated When your account's billing is updated The updated billing object
user.created When a user is created The user object
user.updated When a user is updated The updated user object
user.deleted When a user is deleted The deleted user object
product.created When a product is created The product object
product.updated When a product is updated The updated product object
product.deleted When a product is deleted The deleted product object
policy.created When a policy is created The policy object
policy.updated When a policy is updated The updated policy object
policy.deleted When a policy is deleted The deleted policy object
policy.pool.popped When a key is popped from a pool The popped key object
license.created When a license is created The license object
license.updated When a license is updated The updated license object
license.deleted When a license is deleted The deleted license object
license.expiring-soon When a license is expiring within the next 3 days (up to 1 event will be sent every day until expiration) The expiring license object
license.expired When a license has expired The expired license object
license.check-in-required-soon When a license requires a check-in within the next 3 days (up to 1 event will be sent every day until overdue) The license object
license.check-in-overdue When a license is overdue for check-in The overdue license object
license.validation.succeeded When a license validation succeeds The validated license object
license.validation.failed When a license validation fails The validated license object
license.renewed When a license is renewed The renewed license object
license.revoked When a license is revoked The revoked license object
license.suspended When a license is suspended The suspended license object
license.reinstated When a license is reinstated The reinstated license object
machine.created When a machine is created The machine object
machine.updated When a machine is updated The updated machine object
machine.deleted When a machine is deleted The deleted machine object
key.created When a key is created The key object
key.updated When a key is updated The updated key object
key.deleted When a key is deleted The deleted key object

Example webhook handler

const fetch = require("node-fetch")

async function webhookHandler(req, res) {
  const { data: { id } } = JSON.parse(req.body)

  // Fetch the webhook to validate it and get its most up-to-date state
  const event = await fetch(`https://api.keygen.sh/v1/accounts/<%= account %>/webhook-events/${id}`, {
    method: "GET",
    headers: {
      "Content-Type": "application/vnd.api+json",
      "Accept": "application/vnd.api+json",
      "Authorization": "Bearer <%= token %>"
    }
  })

  const { data, errors } = await event.json()
  if (errors) {
    return // Webhook event does not exist or is invalid
  }

  switch (data.attributes.event) {
    case "user.created":
      const user = JSON.parse(data.attributes.payload)

      // … do something when a user is created e.g. create a Stripe customer

      break
    case "license.created":
      const license = JSON.parse(data.attributes.payload)

      // … do something when a license is created e.g. charge a user

      break
  }

  res.sendStatus(200)
}

linkThe endpoint object

Below you will find the various attributes for the endpoint resource, as well as the endpoint resource's relationships.

When delivering webhook events to your endpoint, an event is considered failed if the endpoint responds with a non-2xx status code. It will automatically be retried with an exponential backoff. We will perform 25 retries over approximately 21 days.

linkAttributes

  • linkurl

    string

    The url that events are dispatched to. Must use the https protocol.

  • linkcreated

    timestampread only

    When the endpoint was created.

  • linkupdated

    timestampread only

    When the endpoint was last updated.

linkRelationships

  • linkaccount

    individual

    The account that the endpoint belongs to.

Example object

{
  "data": {
    "id": "0ed7330f-8d2c-405e-88b6-0a4a327e620c",
    "type": "webhook-endpoints",
    "links": {
      "self": "/v1/accounts/<%= account %>/webhook-endpoints/0ed7330f-8d2c-405e-88b6-0a4a327e620c"
    },
    "attributes": {
      "url": "https://api.example.com/v1/keygen",
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      }
    }
  }
}

linkCreate an endpoint

Creates a new endpoint for the account.

linkAuthentication

  • linkBearer

    required

    An authentication token with admin privileges.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

linkAttributes

  • linkurl

    string, required

    The url that events are dispatched to. Must use the https protocol.

Definition

POST https://api.keygen.sh/v1/accounts/<%= account %>/webhook-endpoints \
  -d '{ "data": { "type": "webhook-endpoints", "attributes": {DATA} } }'

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/webhook-endpoints", {
  method: "POST",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  },
  body: JSON.stringify({
    "data": {
      "type": "webhook-endpoints",
      "attributes": {
        "url": "https://api.example.com/v1/keygen"
      }
    }
  })
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/webhook-endpoints",
  method: .post,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ],
  parameters: [
    "data": [
      "type": "webhook-endpoints",
      "attributes": [
        "url": "https://api.example.com/v1/keygen"
      ]
    ]
  ],
  encoding: JSONEncoding.default
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl -X POST https://api.keygen.sh/v1/accounts/<%= account %>/webhook-endpoints \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>' \
  -d '{
        "data": {
          "type": "webhook-endpoints",
          "attributes": {
            "url": "https://api.example.com/v1/keygen"
          }
        }
      }'

Example response / 201 Created

{
  "data": {
    "id": "0ed7330f-8d2c-405e-88b6-0a4a327e620c",
    "type": "webhook-endpoints",
    "links": {
      "self": "/v1/accounts/<%= account %>/webhook-endpoints/0ed7330f-8d2c-405e-88b6-0a4a327e620c"
    },
    "attributes": {
      "url": "https://api.example.com/v1/keygen",
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      }
    }
  }
}

linkRetrieve an endpoint

Retrieves the details of an existing endpoint.

linkAuthentication

  • linkBearer

    required

    An authentication token with admin privileges.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

  • linkid

    string, required

    The identifier of the webhook-endpoint to be retrieved.

Definition

GET https://api.keygen.sh/v1/accounts/<%= account %>/webhook-endpoints/{ID}

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/webhook-endpoints/0ed7330f-8d2c-405e-88b6-0a4a327e620c", {
  method: "GET",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/webhook-endpoints/0ed7330f-8d2c-405e-88b6-0a4a327e620c",
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl https://api.keygen.sh/v1/accounts/<%= account %>/webhook-endpoints/0ed7330f-8d2c-405e-88b6-0a4a327e620c \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": {
    "id": "0ed7330f-8d2c-405e-88b6-0a4a327e620c",
    "type": "webhook-endpoints",
    "links": {
      "self": "/v1/accounts/<%= account %>/webhook-endpoints/0ed7330f-8d2c-405e-88b6-0a4a327e620c"
    },
    "attributes": {
      "url": "https://api.example.com/v1/keygen",
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      }
    }
  }
}

linkUpdate an endpoint

Updates the specified endpoint resource by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

linkAuthentication

  • linkBearer

    required

    An authentication token with admin privileges.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

  • linkid

    string, required

    The identifier of the webhook endpoint to be updated.

linkAttributes

  • linkurl

    string, optional

    The url that events are dispatched to. Must use the https protocol.

Definition

PATCH https://api.keygen.sh/v1/accounts/<%= account %>/webhook-endpoints/{ID} \
  -d '{ "data": { "type": "webhook-endpoints", "attributes": {DATA} } }'

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/webhook-endpoints/0ed7330f-8d2c-405e-88b6-0a4a327e620c", {
  method: "PATCH",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  },
  body: JSON.stringify({
    "data": {
      "type": "webhook-endpoints",
      "attributes": {
        "url": "https://api.example.com/v2/keygen"
      }
    }
  })
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/webhook-endpoints/0ed7330f-8d2c-405e-88b6-0a4a327e620c",
  method: .patch,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ],
  parameters: [
    "data": [
      "type": "webhook-endpoints",
      "attributes": [
        "url": "https://api.example.com/v2/keygen"
      ]
    ]
  ],
  encoding: JSONEncoding.default
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl -X PATCH https://api.keygen.sh/v1/accounts/<%= account %>/webhook-endpoints/0ed7330f-8d2c-405e-88b6-0a4a327e620c \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>' \
  -d '{
        "data": {
          "type": "webhook-endpoints",
          "attributes": {
            "url": "https://api.example.com/v2/keygen"
          }
        }
      }'

Example response / 200 OK

{
  "data": {
    "id": "0ed7330f-8d2c-405e-88b6-0a4a327e620c",
    "type": "webhook-endpoints",
    "links": {
      "self": "/v1/accounts/<%= account %>/webhook-endpoints/0ed7330f-8d2c-405e-88b6-0a4a327e620c"
    },
    "attributes": {
      "url": "https://api.example.com/v2/keygen",
      "created": "<%= created %>",
      "updated": "<%= updated %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      }
    }
  }
}

linkDelete an endpoint

Permanently deletes an endpoint. It cannot be undone.

linkAuthentication

  • linkBearer

    required

    An authentication token with admin privileges.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

  • linkid

    string, required

    The identifier of the endpoint to be deleted.

Definition

DELETE https://api.keygen.sh/v1/accounts/<%= account %>/webhook-endpoints/{ID}

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/webhook-endpoints/0ed7330f-8d2c-405e-88b6-0a4a327e620c", {
  method: "DELETE",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/webhook-endpoints/0ed7330f-8d2c-405e-88b6-0a4a327e620c",
  method: .delete,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let status = response.response?.statusCode
}
curl -X DELETE https://api.keygen.sh/v1/accounts/<%= account %>/webhook-endpoints/0ed7330f-8d2c-405e-88b6-0a4a327e620c \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 204 No Content

No content

linkList all endpoints

Returns a list of endpoints. The endpoints are returned sorted by creation date, with the most recent endpoints appearing first.

linkAuthentication

  • linkBearer

    required

    An authentication token with admin privileges.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

linkFilters

  • linklimit

    integer, default is10

    A limit on the number of endpoints to be returned. Limit must be a number between 1 and 100.

    https://api.keygen.sh/v1/accounts/<%= account %>/webhook-endpoints?limit=25

  • linkpage

    hash

    Hash containing page size and page number. Page size must be a number between 1 and 100

    https://api.keygen.sh/v1/accounts/<%= account %>/webhook-endpoints?page[size]=15&page[number]=2

Definition

GET https://api.keygen.sh/v1/accounts/<%= account %>/webhook-endpoints{FILTERS}

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/webhook-endpoints?limit=15", {
  method: "GET",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/webhook-endpoints?limit=15",
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl https://api.keygen.sh/v1/accounts/<%= account %>/webhook-endpoints?limit=15 -g \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": [
    {
      "id": "0ed7330f-8d2c-405e-88b6-0a4a327e620c",
      "type": "webhook-endpoints",
      "links": {
        "self": "/v1/accounts/<%= account %>/webhook-endpoints/0ed7330f-8d2c-405e-88b6-0a4a327e620c"
      },
      "attributes": {
        "url": "https://api.example.com/v1/keygen",
        "created": "<%= created %>",
        "updated": "<%= created %>"
      },
      "relationships": {
        "account": {
          "links": {
            "related": "/v1/accounts/<%= account %>"
          },
          "data": {
            "type": "accounts",
            "id": "<%= account %>"
          }
        }
      }
    },
    …
  ]
}

linkThe event object

Below you will find the various attributes for the event resource, as well as the event resource's relationships.

If security is a concern, or if it's important to confirm that Keygen sent the webhook, you should use ONLY the event ID sent within the webhook to then retrieve the remaining details from Keygen. If the event doesn't exist, then it wasn't from us.

linkAttributes

  • linkendpoint

    stringread only

    The endpoint that the event will be sent to.

  • linkpayload

    stringread only

    The event payload in serialized JSON format.

  • linkevent

    stringread only

    The event type.

  • linkstatus

    stringread only

    The current status of the event. Possible statuses are: queued, working, complete, failed, interrupted or unavailable.

  • linkcreated

    timestampread only

    When the event was created.

  • linkupdated

    timestampread only

    When the event was last updated.

linkRelationships

  • linkaccount

    individual

    The account that the event belongs to.

Example object

{
  "data": {
    "id": "e438b26c-79ab-4088-9bbd-17dbb70c429a",
    "type": "webhook-events",
    "meta": {
      "idempotencyToken": "eeb719a7005359c2b1993c90cff455e2749142253c15227d3f7a93048868c5v1"
    },
    "links": {
      "self": "/v1/accounts/<%= account %>/webhook-events/e438b26c-79ab-4088-9bbd-17dbb70c429a"
    },
    "attributes": {
      "endpoint": "https://api.example.com/keygen",
      "payload": "{\"data\":{\"id\":\"438fc352-3fb5-4f0a-ae06-19d6f55ed5f8\",\"type\":\"licenses\",\"links\":{\"self\":\"/v1/accounts/436430b4-de65-4b1d-a120-97b231395502/licenses/438fc352-3fb5-4f0a-ae06-19d6f55ed5f8\"},\"attributes\":{\"key\":\"438fc3523fb54f0aae0619d6f55ed5f8-aeb27205c6f82479f888d83ff54b73e4-4cde9bc9cbac8f245220428cc1d0ab9c-119beb9ae7373524deb53cc20f7b14v1\",\"expiry\":\"2017-01-27T16:05:26.207Z\",\"encrypted\":true,\"metadata\":{},\"created\":\"2017-01-13T16:05:26.207Z\",\"updated\":\"2017-01-13T16:05:26.207Z\"},\"relationships\":{\"account\":{\"links\":{\"related\":\"/v1/accounts/436430b4-de65-4b1d-a120-97b231395502\"},\"data\":{\"type\":\"accounts\",\"id\":\"436430b4-de65-4b1d-a120-97b231395502\"}},\"product\":{\"links\":{\"related\":\"/v1/accounts/436430b4-de65-4b1d-a120-97b231395502/licenses/438fc352-3fb5-4f0a-ae06-19d6f55ed5f8/product\"},\"data\":{\"type\":\"products\",\"id\":\"558c385c-ce9f-483a-8339-f8b71792426f\"}},\"policy\":{\"links\":{\"related\":\"/v1/accounts/436430b4-de65-4b1d-a120-97b231395502/licenses/438fc352-3fb5-4f0a-ae06-19d6f55ed5f8/policy\"},\"data\":{\"type\":\"policies\",\"id\":\"d16e6c26-bfbd-47ae-94d5-d9b899e18cfa\"}},\"user\":{\"links\":{\"related\":\"/v1/accounts/436430b4-de65-4b1d-a120-97b231395502/licenses/438fc352-3fb5-4f0a-ae06-19d6f55ed5f8/user\"},\"data\":{\"type\":\"users\",\"id\":\"7e401525-a2ae-4998-b4a3-84cc2e8dfa2f\"}},\"machines\":{\"links\":{\"related\":\"/v1/accounts/436430b4-de65-4b1d-a120-97b231395502/licenses/438fc352-3fb5-4f0a-ae06-19d6f55ed5f8/machines\"}}}}}",
      "event": "license.created",
      "status": "queued",
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      }
    }
  }
}

linkRetrieve an event

Retrieves the details of an existing event.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to view the resource: either an admin or a product.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

  • linkid

    string, required

    The identifier of the event to be retrieved.

Definition

GET https://api.keygen.sh/v1/accounts/<%= account %>/webhook-events/{ID}

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/webhook-events/e438b26c-79ab-4088-9bbd-17dbb70c429a", {
  method: "GET",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/webhook-events/e438b26c-79ab-4088-9bbd-17dbb70c429a",
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl https://api.keygen.sh/v1/accounts/<%= account %>/webhook-events/e438b26c-79ab-4088-9bbd-17dbb70c429a \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": {
    "id": "e438b26c-79ab-4088-9bbd-17dbb70c429a",
    "type": "webhook-events",
    "meta": {
      "idempotencyToken": "eeb719a7005359c2b1993c90cff455e2749142253c15227d3f7a93048868c5v1"
    },
    "links": {
      "self": "/v1/accounts/<%= account %>/webhook-events/e438b26c-79ab-4088-9bbd-17dbb70c429a"
    },
    "attributes": {
      "endpoint": "https://api.example.com/keygen",
      "payload": "{\"data\":{\"id\":\"438fc352-3fb5-4f0a-ae06-19d6f55ed5f8\",\"type\":\"licenses\",\"links\":{\"self\":\"/v1/accounts/436430b4-de65-4b1d-a120-97b231395502/licenses/438fc352-3fb5-4f0a-ae06-19d6f55ed5f8\"},\"attributes\":{\"key\":\"438fc3523fb54f0aae0619d6f55ed5f8-aeb27205c6f82479f888d83ff54b73e4-4cde9bc9cbac8f245220428cc1d0ab9c-119beb9ae7373524deb53cc20f7b14v1\",\"expiry\":\"2017-01-27T16:05:26.207Z\",\"encrypted\":true,\"metadata\":{},\"created\":\"2017-01-13T16:05:26.207Z\",\"updated\":\"2017-01-13T16:05:26.207Z\"},\"relationships\":{\"account\":{\"links\":{\"related\":\"/v1/accounts/436430b4-de65-4b1d-a120-97b231395502\"},\"data\":{\"type\":\"accounts\",\"id\":\"436430b4-de65-4b1d-a120-97b231395502\"}},\"product\":{\"links\":{\"related\":\"/v1/accounts/436430b4-de65-4b1d-a120-97b231395502/licenses/438fc352-3fb5-4f0a-ae06-19d6f55ed5f8/product\"},\"data\":{\"type\":\"products\",\"id\":\"558c385c-ce9f-483a-8339-f8b71792426f\"}},\"policy\":{\"links\":{\"related\":\"/v1/accounts/436430b4-de65-4b1d-a120-97b231395502/licenses/438fc352-3fb5-4f0a-ae06-19d6f55ed5f8/policy\"},\"data\":{\"type\":\"policies\",\"id\":\"d16e6c26-bfbd-47ae-94d5-d9b899e18cfa\"}},\"user\":{\"links\":{\"related\":\"/v1/accounts/436430b4-de65-4b1d-a120-97b231395502/licenses/438fc352-3fb5-4f0a-ae06-19d6f55ed5f8/user\"},\"data\":{\"type\":\"users\",\"id\":\"7e401525-a2ae-4998-b4a3-84cc2e8dfa2f\"}},\"machines\":{\"links\":{\"related\":\"/v1/accounts/436430b4-de65-4b1d-a120-97b231395502/licenses/438fc352-3fb5-4f0a-ae06-19d6f55ed5f8/machines\"}}}}}",
      "event": "license.created",
      "status": "queued",
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      }
    }
  }
}

linkList all events

Returns a list of events. The events are returned sorted by creation date, with the most recent events appearing first.

linkAuthentication

  • linkBearer

    required

    An authentication token with admin privileges.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

linkFilters

  • linklimit

    integer, default is10

    A limit on the number of events to be returned. Limit must be a number between 1 and 100.

    https://api.keygen.sh/v1/accounts/<%= account %>/webhook-events?limit=25

  • linkpage

    hash

    Hash containing page size and page number. Page size must be a number between 1 and 100

    https://api.keygen.sh/v1/accounts/<%= account %>/webhook-events?page[size]=15&page[number]=2

  • linkevents

    array

    Array containing events to filter by.

    https://api.keygen.sh/v1/accounts/<%= account %>/webhook-events?events[]=license.deleted&events[]=license.revoked

Definition

GET https://api.keygen.sh/v1/accounts/<%= account %>/webhook-events{FILTERS}

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/webhook-events?limit=15", {
  method: "GET",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/webhook-events?limit=15",
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl https://api.keygen.sh/v1/accounts/<%= account %>/webhook-events?limit=15 -g \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": [
    {
      "id": "e438b26c-79ab-4088-9bbd-17dbb70c429a",
      "type": "webhook-events",
      "meta": {
        "idempotencyToken": "eeb719a7005359c2b1993c90cff455e2749142253c15227d3f7a93048868c5v1"
      },
      "links": {
        "self": "/v1/accounts/<%= account %>/webhook-events/e438b26c-79ab-4088-9bbd-17dbb70c429a"
      },
      "attributes": {
        "endpoint": "https://api.example.com/keygen",
        "payload": "{\"data\":{\"id\":\"438fc352-3fb5-4f0a-ae06-19d6f55ed5f8\",\"type\":\"licenses\",\"links\":{\"self\":\"/v1/accounts/436430b4-de65-4b1d-a120-97b231395502/licenses/438fc352-3fb5-4f0a-ae06-19d6f55ed5f8\"},\"attributes\":{\"key\":\"438fc3523fb54f0aae0619d6f55ed5f8-aeb27205c6f82479f888d83ff54b73e4-4cde9bc9cbac8f245220428cc1d0ab9c-119beb9ae7373524deb53cc20f7b14v1\",\"expiry\":\"2017-01-27T16:05:26.207Z\",\"encrypted\":true,\"metadata\":{},\"created\":\"2017-01-13T16:05:26.207Z\",\"updated\":\"2017-01-13T16:05:26.207Z\"},\"relationships\":{\"account\":{\"links\":{\"related\":\"/v1/accounts/436430b4-de65-4b1d-a120-97b231395502\"},\"data\":{\"type\":\"accounts\",\"id\":\"436430b4-de65-4b1d-a120-97b231395502\"}},\"product\":{\"links\":{\"related\":\"/v1/accounts/436430b4-de65-4b1d-a120-97b231395502/licenses/438fc352-3fb5-4f0a-ae06-19d6f55ed5f8/product\"},\"data\":{\"type\":\"products\",\"id\":\"558c385c-ce9f-483a-8339-f8b71792426f\"}},\"policy\":{\"links\":{\"related\":\"/v1/accounts/436430b4-de65-4b1d-a120-97b231395502/licenses/438fc352-3fb5-4f0a-ae06-19d6f55ed5f8/policy\"},\"data\":{\"type\":\"policies\",\"id\":\"d16e6c26-bfbd-47ae-94d5-d9b899e18cfa\"}},\"user\":{\"links\":{\"related\":\"/v1/accounts/436430b4-de65-4b1d-a120-97b231395502/licenses/438fc352-3fb5-4f0a-ae06-19d6f55ed5f8/user\"},\"data\":{\"type\":\"users\",\"id\":\"7e401525-a2ae-4998-b4a3-84cc2e8dfa2f\"}},\"machines\":{\"links\":{\"related\":\"/v1/accounts/436430b4-de65-4b1d-a120-97b231395502/licenses/438fc352-3fb5-4f0a-ae06-19d6f55ed5f8/machines\"}}}}}",
        "event": "license.created",
        "status": "queued",
        "created": "<%= created %>",
        "updated": "<%= created %>"
      },
      "relationships": {
        "account": {
          "links": {
            "related": "/v1/accounts/<%= account %>"
          },
          "data": {
            "type": "accounts",
            "id": "<%= account %>"
          }
        }
      }
    },
    …
  ]
}

linkEvent actions

Actions for the event resource.

linkManually retry event

Action to manually retry an event. This creates a new event resource with an identical idempotency token.

Be aware that failed events are automatically retried with an exponential backoff. We will perform 25 retries over approximately 21 days. If you're not watching idempotency tokens, manually retrying an event may result in stale or duplicate data being sent to your endpoints. An event is considered failed if the server responds with a non-2xx status code.

linkAuthentication

  • linkBearer

    required

    An authentication token with admin privileges.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

  • linkid

    string, required

    The identifier of the event to retry.

Definition

POST https://api.keygen.sh/v1/accounts/<%= account %>/webhook-events/e438b26c-79ab-4088-9bbd-17dbb70c429a/actions/retry

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/webhook-events/e438b26c-79ab-4088-9bbd-17dbb70c429a/actions/retry", {
  method: "POST",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/webhook-events/e438b26c-79ab-4088-9bbd-17dbb70c429a/actions/retry",
  method: .post,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl -X POST https://api.keygen.sh/v1/accounts/<%= account %>/webhook-events/e438b26c-79ab-4088-9bbd-17dbb70c429a/actions/retry \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 201 Created

{
  "data": {
    "id": "3119ed21-2f9e-4aa9-8210-5ed0e73f9bef",
    "type": "webhook-events",
    "meta": {
      "idempotencyToken": "eeb719a7005359c2b1993c90cff455e2749142253c15227d3f7a93048868c5v1"
    },
    "links": {
      "self": "/v1/accounts/<%= account %>/webhook-events/3119ed21-2f9e-4aa9-8210-5ed0e73f9bef"
    },
    "attributes": {
      "endpoint": "https://api.example.com/keygen",
      "payload": "{\"data\":{\"id\":\"438fc352-3fb5-4f0a-ae06-19d6f55ed5f8\",\"type\":\"licenses\",\"links\":{\"self\":\"/v1/accounts/436430b4-de65-4b1d-a120-97b231395502/licenses/438fc352-3fb5-4f0a-ae06-19d6f55ed5f8\"},\"attributes\":{\"key\":\"438fc3523fb54f0aae0619d6f55ed5f8-aeb27205c6f82479f888d83ff54b73e4-4cde9bc9cbac8f245220428cc1d0ab9c-119beb9ae7373524deb53cc20f7b14v1\",\"expiry\":\"2017-01-27T16:05:26.207Z\",\"encrypted\":true,\"metadata\":{},\"created\":\"2017-01-13T16:05:26.207Z\",\"updated\":\"2017-01-13T16:05:26.207Z\"},\"relationships\":{\"account\":{\"links\":{\"related\":\"/v1/accounts/436430b4-de65-4b1d-a120-97b231395502\"},\"data\":{\"type\":\"accounts\",\"id\":\"436430b4-de65-4b1d-a120-97b231395502\"}},\"product\":{\"links\":{\"related\":\"/v1/accounts/436430b4-de65-4b1d-a120-97b231395502/licenses/438fc352-3fb5-4f0a-ae06-19d6f55ed5f8/product\"},\"data\":{\"type\":\"products\",\"id\":\"558c385c-ce9f-483a-8339-f8b71792426f\"}},\"policy\":{\"links\":{\"related\":\"/v1/accounts/436430b4-de65-4b1d-a120-97b231395502/licenses/438fc352-3fb5-4f0a-ae06-19d6f55ed5f8/policy\"},\"data\":{\"type\":\"policies\",\"id\":\"d16e6c26-bfbd-47ae-94d5-d9b899e18cfa\"}},\"user\":{\"links\":{\"related\":\"/v1/accounts/436430b4-de65-4b1d-a120-97b231395502/licenses/438fc352-3fb5-4f0a-ae06-19d6f55ed5f8/user\"},\"data\":{\"type\":\"users\",\"id\":\"7e401525-a2ae-4998-b4a3-84cc2e8dfa2f\"}},\"machines\":{\"links\":{\"related\":\"/v1/accounts/436430b4-de65-4b1d-a120-97b231395502/licenses/438fc352-3fb5-4f0a-ae06-19d6f55ed5f8/machines\"}}}}}",
      "event": "license.created",
      "status": "queued",
      "created": "<%= updated %>",
      "updated": "<%= updated %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      }
    }
  }
}

linkProfiles

linkRetrieve profile

Retrieves the details of the currently authenticated bearer.

linkAuthentication

  • linkBearer

    required

    An authentication token.

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

Definition

GET https://api.keygen.sh/v1/accounts/<%= account %>/profile

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/profile", {
  method: "GET",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})

const { data, errors } = await response.json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/profile",
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
curl https://api.keygen.sh/v1/accounts/<%= account %>/profile \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": {
    "id": "a5a154d2-f026-40fa-bc8d-a7e3ca415298",
    "type": "users",
    "attributes": {
      "fullName": "John Doe",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "role": "admin",
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "products": {
        "links": {
          "related": "/v1/accounts/<%= account %>/profiles/a5a154d2-f026-40fa-bc8d-a7e3ca415298/products"
        }
      },
      "licenses": {
        "links": {
          "related": "/v1/accounts/<%= account %>/profiles/a5a154d2-f026-40fa-bc8d-a7e3ca415298/licenses"
        }
      },
      "machines": {
        "links": {
          "related": "/v1/accounts/<%= account %>/profiles/a5a154d2-f026-40fa-bc8d-a7e3ca415298/machines"
        }
      },
      "tokens": {
        "links": {
          "related": "/v1/accounts/<%= account %>/profiles/a5a154d2-f026-40fa-bc8d-a7e3ca415298/tokens"
        }
      }
    }
  }
}

linkPasswords

linkForgot password

Request a password reset for a user. This will send an email to the user, if it is a valid email address. The email will contain a link leading to a password reset form securely hosted by Keygen.

In the future, we will support the use of custom domains and branding or the ability to respond to reset requests via webhook events.

linkAuthentication

linkParameters

  • linkaccount

    string, required

    The identifier or slug of the account.

linkMeta

  • linkemail

    string, required

    The email of the user.

Definition

POST https://api.keygen.sh/v1/accounts/<%= account %>/passwords \
  -d '{ "meta": {DATA} }'

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/passwords", {
  method: "POST",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json"
  },
  body: JSON.stringify({
    "meta": {
      "email": "[email protected]"
    }
  })
})
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/passwords",
  method: .post,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json"
  ],
  parameters: [
    "meta": [
      "email": "[email protected]"
    ]
  ],
  encoding: JSONEncoding.default
).responseJSON { response in
  let status = response.response?.statusCode
}
curl -X POST https://api.keygen.sh/v1/accounts/<%= account %>/passwords \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -d '{
        "meta": {
          "email": "[email protected]"
        }
      }'

Example response / 202 Accepted

No content