Tokens

The token object
Generate a token
Retrieve a token
Regenerate a token
Revoke a token
List all tokens

The token object

Keygen authenticates your API requests using tokens. 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. Tokens with an expiry will automatically be deleted 90 days after their expiry, unless renewed.

Admin, environment, 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 can authenticate as one of your users or use a license token to perform client-side machine activations. Admin, environment, and product tokens should only be used server-side.

Attributes

data.attributes.kind
stringread only
The kind of token, based on its bearer.
Options
- activation-token: A license token with permission to activate and deactivate the machines for a given license.
- product-token: An internal administrative token with permission to manage the entire product and its resources, usually for server-side use.
- user-token: A normal user of one or more of your products, with limited permission to manage their own resources.
- support-token: An internal administrative user of your Keygen account, with a limited subset of permissions.
- sales-token: An internal administrative user of your Keygen account, with a limited subset of permissions.
- developer-token: An internal administrative user of your Keygen account, with permission to manage most resources.
- admin-token: An internal administrative user of your Keygen account, with permission to manage the entire account.
data.attributes.token
stringread only
The raw token of the token. This attribute is only available to read directly after token generation. This is the value you will use to authenticate with when sending requests to our API.
data.attributes.name
string
An optional name for the token. This can be used to easily identify tokens at a glance.
data.attributes.expiry
timestamp (iso8601)read only
The timestamp for when the token expires. Requests using an expired token will be rejected.
data.attributes.permissions
array<string>ent onlyThese attributes are only available for accounts on an Ent tier.
The permissions for the token. Default and available permissions, dependent on bearer, are covered here.
data.attributes.maxActivations
integer
The maximum amount of machine activations this token may perform. This attribute is only applicable to license tokens.
data.attributes.activations
integerread only
The number of machine activations that have been performed by this token. This attribute is only applicable to license tokens.
data.attributes.maxDeactivations
integer
The maximum amount of machine deactivations this token may perform. This attribute is only applicable to license tokens.
data.attributes.deactivations
integerread only
The number of machine deactivations that have been performed by this token. This attribute is only applicable to license tokens.
data.attributes.created
timestamp (iso8601)read only
When the token was created.
data.attributes.updated
timestamp (iso8601)read only
When the token was last updated.

Relationships

data.relationships.account
individual
The account that the token belongs to.
data.relationships.environment
individualent onlyThese relationships are only available for accounts on an Ent tier.
The environment that the token belongs to.
data.relationships.bearer
individual
The bearer of the token.

Example object

{
  "data": {
    "id": "6a7562be-b302-43d2-a550-30d6026247aa",
    "type": "tokens",
    "attributes": {
      "kind": "user-token",
      "token": "user-57c1cdc2a084f0ebd46850e5742b1f0bca47d1ca5f5262f6c5969fec8dbd530dv3",
      "expiry": "2022-03-15T19:27:50.440Z",
      "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>"
        }
      },
      "bearer": {
        "links": {
          "related": "/v1/accounts/<account>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298"
        },
        "data": {
          "type": "users",
          "id": "a5a154d2-f026-40fa-bc8d-a7e3ca415298"
        }
      }
    }
  }
}
{
  "data": {
    "id": "6a7562be-b302-43d2-a550-30d6026247aa",
    "type": "tokens",
    "attributes": {
      "kind": "user-token",
      "token": "user-57c1cdc2a084f0ebd46850e5742b1f0bca47d1ca5f5262f6c5969fec8dbd530dv3",
      "expiry": "2022-03-15T19:27:50.440Z",
      "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>"
        }
      },
      "bearer": {
        "links": {
          "related": "/v1/accounts/<account>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298"
        },
        "data": {
          "type": "users",
          "id": "a5a154d2-f026-40fa-bc8d-a7e3ca415298"
        }
      }
    }
  }
}

Generate a token

Generate a new token resource for a user, using the user's email and password. Keygen does not store your tokens for security reasons. After a token is generated, it cannot be recovered if lost. The token will need to be revoked if lost, and a new token should be generated. Alternatively, the existing token can be regenerated (rolled).

By default, user tokens expire in 2 weeks, and admin tokens do not expire. A custom expiry may be provided in the token generate request. If the user does not have a password, a token must be generated via the user's token relationship

To generate a token for an environment, see the environment token relationship.

To generate a token for a product, see the product token relationship.

To generate a license token, see the license token relationship.

Authentication

Basic
required
The email and password of the user. Credentials MUST use a colon (i.e. ":") to separate the email and password (i.e. "EMAIL:PASSWORD"), and those credentials MUST then be base64 encoded.

URL Parameters

<account>
stringrequired
The identifier (UUID) or slug of your Keygen account.

Attributes

data.attributes.name
stringoptional
An optional name for the token. This can be used to easily identify tokens at a glance.
data.attributes.expiry
timestamp (iso8601)optional
The timestamp for when the token expires. Requests using an expired token will be rejected.
data.attributes.permissions
array<string>default=["*"]ent onlyThese attributes are only available for accounts on an Ent tier.
The permissions for the token. Available permissions, dependent on the bearer, are covered here. By default, it is set to a wildcard `*`, which inherits all permissions from the token bearer.

Returns

A 201 Created response will be returned along with the new token object. The token attribute of the token object, which is used for authentication, is ONLY readable directly after creation. Please securely store this value for later use, otherwise the token may need to be regenerated.

If an OTP_REQUIRED error code is returned, this signals that the user has a second factor enabled and you must prompt them for their OTP code. If an OTP_INVALID error code is returned, the provided OTP code was invalid or expired.

Upon error, an errors object will be returned along with an HTTP status code indicating the type of error. When an error occurs, the data property will not be included.

Definition

https://api.keygen.sh/v1/accounts/<account>/tokens
https://api.keygen.sh/v1/accounts/<account>/tokens

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: {
    "Accept": "application/vnd.api+json",
    "Authorization": `Basic ${credentials}`
  }
})
 
const { data, errors } = await response.json()
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: {
    "Accept": "application/vnd.api+json",
    "Authorization": `Basic ${credentials}`
  }
})

const { data, errors } = await response.json()
import requests
import json
 
res = requests.post(
  "https://api.keygen.sh/v1/accounts/<account>/tokens",
  headers={ "Accept": "application/vnd.api+json" },
  auth=("<email>", "<password>")
).json()
import requests
import json

res = requests.post(
  "https://api.keygen.sh/v1/accounts/<account>/tokens",
  headers={ "Accept": "application/vnd.api+json" },
  auth=("<email>", "<password>")
).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: [
    "Accept": "application/vnd.api+json",
    "Authorization": "Basic \(credentials)"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
import SwiftyJSON
import Alamofire

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

Alamofire.request("https://api.keygen.sh/v1/accounts/<account>/tokens",
  method: .post,
  headers: [
    "Accept": "application/vnd.api+json",
    "Authorization": "Basic \(credentials)"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
using RestSharp;
using System;
using System.Text;
 
var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes("<email>:<password>"));
 
var client = new RestClient("https://api.keygen.sh/v1/accounts/<account>");
var request = new RestRequest("tokens", Method.POST);
 
request.AddHeader("Accept", "application/vnd.api+json");
request.AddHeader("Authorization", $"Basic {credentials}");
 
var response = client.Execute(request);
using RestSharp;
using System;
using System.Text;

var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes("<email>:<password>"));

var client = new RestClient("https://api.keygen.sh/v1/accounts/<account>");
var request = new RestRequest("tokens", Method.POST);

request.AddHeader("Accept", "application/vnd.api+json");
request.AddHeader("Authorization", $"Basic {credentials}");

var response = client.Execute(request);
import com.mashape.unirest.http.exceptions.*
import com.mashape.unirest.http.*
 
val res = Unirest.post("https://api.keygen.sh/v1/accounts/<account>/tokens")
  .header("Accept", "application/vnd.api+json")
  .basicAuth("<email>", "<password>")
  .asJson()
import com.mashape.unirest.http.exceptions.*
import com.mashape.unirest.http.*

val res = Unirest.post("https://api.keygen.sh/v1/accounts/<account>/tokens")
  .header("Accept", "application/vnd.api+json")
  .basicAuth("<email>", "<password>")
  .asJson()
import com.mashape.unirest.http.exceptions.*;
import com.mashape.unirest.http.*;
 
HttpResponse<JsonNode> res = Unirest.post("https://api.keygen.sh/v1/accounts/<account>/tokens")
  .header("Accept", "application/vnd.api+json")
  .basicAuth("<email>", "<password>")
  .asJson();
import com.mashape.unirest.http.exceptions.*;
import com.mashape.unirest.http.*;

HttpResponse<JsonNode> res = Unirest.post("https://api.keygen.sh/v1/accounts/<account>/tokens")
  .header("Accept", "application/vnd.api+json")
  .basicAuth("<email>", "<password>")
  .asJson();
#include <iostream>
#include <string>
#include <cpprest/http_client.h>
#include <cpprest/filestream.h>
 
using namespace std;
using namespace web;
using namespace web::http;
using namespace web::http::client;
using namespace utility;
 
http_client_config config;
credentials cred("<email>", "<password>");
config.set_credentials(cred);
 
http_client client("https://api.keygen.sh/v1/accounts/<account>", config);
http_request req;
 
req.headers().add("Accept", "application/json");
 
req.set_request_uri("/tokens");
req.set_method(methods::POST);
 
client.request(req)
  .then([](http_response res)
  {
    auto data = res.extract_json().get();
  })
  .wait();
#include <iostream>
#include <string>
#include <cpprest/http_client.h>
#include <cpprest/filestream.h>

using namespace std;
using namespace web;
using namespace web::http;
using namespace web::http::client;
using namespace utility;

http_client_config config;
credentials cred("<email>", "<password>");
config.set_credentials(cred);

http_client client("https://api.keygen.sh/v1/accounts/<account>", config);
http_request req;

req.headers().add("Accept", "application/json");

req.set_request_uri("/tokens");
req.set_method(methods::POST);

client.request(req)
  .then([](http_response res)
  {
    auto data = res.extract_json().get();
  })
  .wait();
curl -X POST https://api.keygen.sh/v1/accounts/<account>/tokens \
  -H 'Accept: application/vnd.api+json' \
  -u "<email>:<password>"
curl -X POST https://api.keygen.sh/v1/accounts/<account>/tokens \
  -H 'Accept: application/vnd.api+json' \
  -u "<email>:<password>"

Example response / 201 Created

{
  "data": {
    "id": "6a7562be-b302-43d2-a550-30d6026247aa",
    "type": "tokens",
    "attributes": {
      "kind": "user-token",
      "token": "user-f4869386e3b6b39d1f42949131f97a39b42f9a74c553ba7244bbed9d1f79f106v3",
      "expiry": "2022-03-15T19:27:50.440Z",
      "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>"
        }
      },
      "bearer": {
        "links": {
          "related": "/v1/accounts/<account>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298"
        },
        "data": {
          "type": "users",
          "id": "a5a154d2-f026-40fa-bc8d-a7e3ca415298"
        }
      }
    }
  }
}
{
  "data": {
    "id": "6a7562be-b302-43d2-a550-30d6026247aa",
    "type": "tokens",
    "attributes": {
      "kind": "user-token",
      "token": "user-f4869386e3b6b39d1f42949131f97a39b42f9a74c553ba7244bbed9d1f79f106v3",
      "expiry": "2022-03-15T19:27:50.440Z",
      "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>"
        }
      },
      "bearer": {
        "links": {
          "related": "/v1/accounts/<account>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298"
        },
        "data": {
          "type": "users",
          "id": "a5a154d2-f026-40fa-bc8d-a7e3ca415298"
        }
      }
    }
  }
}

Retrieve a token

Retrieves the details of an existing token.

Authentication

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

URL Parameters

<account>
stringrequired
The identifier (UUID) or slug of your Keygen account.
<id>
stringrequired
The identifier (UUID) of the token to be retrieved.

Returns

A 200 OK response will be returned along with a token object.

Upon error, an errors object will be returned along with an HTTP status code indicating the type of error. When an error occurs, the data property will not be included.

Definition

https://api.keygen.sh/v1/accounts/<account>/tokens/<id>
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: {
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <token>"
  }
})
 
const { data, errors } = await response.json()
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: {
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <token>"
  }
})

const { data, errors } = await response.json()
import requests
import json
 
res = requests.get(
  "https://api.keygen.sh/v1/accounts/<account>/tokens/6a7562be-b302-43d2-a550-30d6026247aa",
  headers={
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <token>"
  }
).json()
import requests
import json

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

Alamofire.request("https://api.keygen.sh/v1/accounts/<account>/tokens/6a7562be-b302-43d2-a550-30d6026247aa",
  headers: [
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <token>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
using RestSharp;
 
var client = new RestClient("https://api.keygen.sh/v1/accounts/<account>");
var request = new RestRequest(
  "tokens/6a7562be-b302-43d2-a550-30d6026247aa",
  Method.GET
);
 
request.AddHeader("Accept", "application/vnd.api+json");
request.AddHeader("Authorization", "Bearer <token>");
 
var response = client.Execute(request);
using RestSharp;

var client = new RestClient("https://api.keygen.sh/v1/accounts/<account>");
var request = new RestRequest(
  "tokens/6a7562be-b302-43d2-a550-30d6026247aa",
  Method.GET
);

request.AddHeader("Accept", "application/vnd.api+json");
request.AddHeader("Authorization", "Bearer <token>");

var response = client.Execute(request);
import com.mashape.unirest.http.exceptions.*
import com.mashape.unirest.http.*
 
val res = Unirest.get("https://api.keygen.sh/v1/accounts/<account>/tokens/6a7562be-b302-43d2-a550-30d6026247aa")
  .header("Authorization", "Bearer <token>")
  .header("Accept", "application/vnd.api+json")
  .asJson()
import com.mashape.unirest.http.exceptions.*
import com.mashape.unirest.http.*

val res = Unirest.get("https://api.keygen.sh/v1/accounts/<account>/tokens/6a7562be-b302-43d2-a550-30d6026247aa")
  .header("Authorization", "Bearer <token>")
  .header("Accept", "application/vnd.api+json")
  .asJson()
import com.mashape.unirest.http.exceptions.*;
import com.mashape.unirest.http.*;
 
HttpResponse<JsonNode> res = Unirest.get("https://api.keygen.sh/v1/accounts/<account>/tokens/6a7562be-b302-43d2-a550-30d6026247aa")
  .header("Authorization", "Bearer <token>")
  .header("Accept", "application/vnd.api+json")
  .asJson();
import com.mashape.unirest.http.exceptions.*;
import com.mashape.unirest.http.*;

HttpResponse<JsonNode> res = Unirest.get("https://api.keygen.sh/v1/accounts/<account>/tokens/6a7562be-b302-43d2-a550-30d6026247aa")
  .header("Authorization", "Bearer <token>")
  .header("Accept", "application/vnd.api+json")
  .asJson();
#include <iostream>
#include <string>
#include <cpprest/http_client.h>
#include <cpprest/filestream.h>
 
using namespace std;
using namespace web;
using namespace web::http;
using namespace web::http::client;
using namespace utility;
 
http_client client("https://api.keygen.sh/v1/accounts/<account>");
http_request req;
 
req.headers().add("Authorization", "Bearer <token>");
req.headers().add("Accept", "application/json");
 
req.set_request_uri("/tokens/6a7562be-b302-43d2-a550-30d6026247aa");
req.set_method(methods::GET);
 
client.request(req)
  .then([](http_response res) {
    auto data = res.extract_json().get();
  })
  .wait();
#include <iostream>
#include <string>
#include <cpprest/http_client.h>
#include <cpprest/filestream.h>

using namespace std;
using namespace web;
using namespace web::http;
using namespace web::http::client;
using namespace utility;

http_client client("https://api.keygen.sh/v1/accounts/<account>");
http_request req;

req.headers().add("Authorization", "Bearer <token>");
req.headers().add("Accept", "application/json");

req.set_request_uri("/tokens/6a7562be-b302-43d2-a550-30d6026247aa");
req.set_method(methods::GET);

client.request(req)
  .then([](http_response res) {
    auto data = res.extract_json().get();
  })
  .wait();
curl https://api.keygen.sh/v1/accounts/<account>/tokens/6a7562be-b302-43d2-a550-30d6026247aa \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <token>'
curl https://api.keygen.sh/v1/accounts/<account>/tokens/6a7562be-b302-43d2-a550-30d6026247aa \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <token>'

Example response / 200 OK

{
  "data": {
    "id": "6a7562be-b302-43d2-a550-30d6026247aa",
    "type": "tokens",
    "attributes": {
      "kind": "admin-token",
      "expiry": "2022-03-15T19:27:50.440Z",
      "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>"
        }
      },
      "bearer": {
        "links": {
          "related": "/v1/accounts/<account>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298"
        },
        "data": {
          "type": "users",
          "id": "a5a154d2-f026-40fa-bc8d-a7e3ca415298"
        }
      }
    }
  }
}
{
  "data": {
    "id": "6a7562be-b302-43d2-a550-30d6026247aa",
    "type": "tokens",
    "attributes": {
      "kind": "admin-token",
      "expiry": "2022-03-15T19:27:50.440Z",
      "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>"
        }
      },
      "bearer": {
        "links": {
          "related": "/v1/accounts/<account>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298"
        },
        "data": {
          "type": "users",
          "id": "a5a154d2-f026-40fa-bc8d-a7e3ca415298"
        }
      }
    }
  }
}

Regenerate a token

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

Authentication

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

URL Parameters

<account>
stringrequired
The identifier (UUID) or slug of your Keygen account.
<id>
stringoptional
The identifier (UUID) of the token to be regenerated. If omitted, the token used to authenticate will be regenerated.

Returns

A 200 OK response will be returned along with the regenerated token object.

Upon error, an errors object will be returned along with an HTTP status code indicating the type of error. When an error occurs, the data property will not be included.

Definition

https://api.keygen.sh/v1/accounts/<account>/tokens/<id>
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: {
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <token>"
  }
})
 
const { data, errors } = await response.json()
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: {
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <token>"
  }
})

const { data, errors } = await response.json()
import requests
import json
 
res = requests.put(
  "https://api.keygen.sh/v1/accounts/<account>/tokens/6a7562be-b302-43d2-a550-30d6026247aa",
  headers={
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <token>"
  }
).json()
import requests
import json

res = requests.put(
  "https://api.keygen.sh/v1/accounts/<account>/tokens/6a7562be-b302-43d2-a550-30d6026247aa",
  headers={
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <token>"
  }
).json()
import SwiftyJSON
import Alamofire
 
Alamofire.request("https://api.keygen.sh/v1/accounts/<account>/tokens/6a7562be-b302-43d2-a550-30d6026247aa",
  method: .put,
  headers: [
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <token>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<account>/tokens/6a7562be-b302-43d2-a550-30d6026247aa",
  method: .put,
  headers: [
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <token>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
using RestSharp;
 
var client = new RestClient("https://api.keygen.sh/v1/accounts/<account>");
var request = new RestRequest(
  "tokens/6a7562be-b302-43d2-a550-30d6026247aa",
  Method.PUT
);
 
request.AddHeader("Accept", "application/vnd.api+json");
request.AddHeader("Authorization", "Bearer <token>");
 
var response = client.Execute(request);
using RestSharp;

var client = new RestClient("https://api.keygen.sh/v1/accounts/<account>");
var request = new RestRequest(
  "tokens/6a7562be-b302-43d2-a550-30d6026247aa",
  Method.PUT
);

request.AddHeader("Accept", "application/vnd.api+json");
request.AddHeader("Authorization", "Bearer <token>");

var response = client.Execute(request);
import com.mashape.unirest.http.exceptions.*
import com.mashape.unirest.http.*
 
val res = Unirest.put("https://api.keygen.sh/v1/accounts/<account>/tokens/6a7562be-b302-43d2-a550-30d6026247aa")
  .header("Authorization", "Bearer <token>")
  .header("Accept", "application/vnd.api+json")
  .asJson()
import com.mashape.unirest.http.exceptions.*
import com.mashape.unirest.http.*

val res = Unirest.put("https://api.keygen.sh/v1/accounts/<account>/tokens/6a7562be-b302-43d2-a550-30d6026247aa")
  .header("Authorization", "Bearer <token>")
  .header("Accept", "application/vnd.api+json")
  .asJson()
import com.mashape.unirest.http.exceptions.*;
import com.mashape.unirest.http.*;
 
HttpResponse<JsonNode> res = Unirest.put("https://api.keygen.sh/v1/accounts/<account>/tokens/6a7562be-b302-43d2-a550-30d6026247aa")
  .header("Authorization", "Bearer <token>")
  .header("Accept", "application/vnd.api+json")
  .asJson();
import com.mashape.unirest.http.exceptions.*;
import com.mashape.unirest.http.*;

HttpResponse<JsonNode> res = Unirest.put("https://api.keygen.sh/v1/accounts/<account>/tokens/6a7562be-b302-43d2-a550-30d6026247aa")
  .header("Authorization", "Bearer <token>")
  .header("Accept", "application/vnd.api+json")
  .asJson();
#include <iostream>
#include <string>
#include <cpprest/http_client.h>
#include <cpprest/filestream.h>
 
using namespace std;
using namespace web;
using namespace web::http;
using namespace web::http::client;
using namespace utility;
 
http_client client("https://api.keygen.sh/v1/accounts/<account>");
http_request req;
 
req.headers().add("Authorization", "Bearer <token>");
req.headers().add("Accept", "application/json");
 
req.set_request_uri("/tokens/6a7562be-b302-43d2-a550-30d6026247aa");
req.set_method(methods::PUT);
 
client.request(req)
  .then([](http_response res) {
    auto data = res.extract_json().get();
  })
  .wait();
#include <iostream>
#include <string>
#include <cpprest/http_client.h>
#include <cpprest/filestream.h>

using namespace std;
using namespace web;
using namespace web::http;
using namespace web::http::client;
using namespace utility;

http_client client("https://api.keygen.sh/v1/accounts/<account>");
http_request req;

req.headers().add("Authorization", "Bearer <token>");
req.headers().add("Accept", "application/json");

req.set_request_uri("/tokens/6a7562be-b302-43d2-a550-30d6026247aa");
req.set_method(methods::PUT);

client.request(req)
  .then([](http_response res) {
    auto data = res.extract_json().get();
  })
  .wait();
curl -X PUT https://api.keygen.sh/v1/accounts/<account>/tokens/6a7562be-b302-43d2-a550-30d6026247aa \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <token>'
curl -X PUT https://api.keygen.sh/v1/accounts/<account>/tokens/6a7562be-b302-43d2-a550-30d6026247aa \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <token>'

Example response / 200 OK

{
  "data": {
    "id": "6a7562be-b302-43d2-a550-30d6026247aa",
    "type": "tokens",
    "attributes": {
      "kind": "user-token",
      "token": "user-72abcf7e9bce107df746fab6751f875aad7801d8edc7b9b9afb2f97ee53b59e7v3",
      "expiry": "2022-03-15T19:27:50.440Z",
      "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>"
        }
      },
      "bearer": {
        "links": {
          "related": "/v1/accounts/<account>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298"
        },
        "data": {
          "type": "users",
          "id": "a5a154d2-f026-40fa-bc8d-a7e3ca415298"
        }
      }
    }
  }
}
{
  "data": {
    "id": "6a7562be-b302-43d2-a550-30d6026247aa",
    "type": "tokens",
    "attributes": {
      "kind": "user-token",
      "token": "user-72abcf7e9bce107df746fab6751f875aad7801d8edc7b9b9afb2f97ee53b59e7v3",
      "expiry": "2022-03-15T19:27:50.440Z",
      "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>"
        }
      },
      "bearer": {
        "links": {
          "related": "/v1/accounts/<account>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298"
        },
        "data": {
          "type": "users",
          "id": "a5a154d2-f026-40fa-bc8d-a7e3ca415298"
        }
      }
    }
  }
}

Revoke a token

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

Authentication

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

URL Parameters

<account>
stringrequired
The identifier (UUID) or slug of your Keygen account.
<id>
stringrequired
The identifier (UUID) of the token to be revoked.

Returns

A 204 No Content response will be returned.

Upon error, an errors object will be returned along with an HTTP status code indicating the type of error. When an error occurs, the data property will not be included.

Definition

https://api.keygen.sh/v1/accounts/<account>/tokens/<id>
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: {
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <token>"
  }
})
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: {
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <token>"
  }
})
import requests
 
res = requests.delete(
  "https://api.keygen.sh/v1/accounts/<account>/tokens/6a7562be-b302-43d2-a550-30d6026247aa",
  headers={
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <token>"
  }
)
import requests

res = requests.delete(
  "https://api.keygen.sh/v1/accounts/<account>/tokens/6a7562be-b302-43d2-a550-30d6026247aa",
  headers={
    "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: [
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <token>"
  ]
).responseJSON { response in
  let status = response.response?.statusCode
}
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<account>/tokens/6a7562be-b302-43d2-a550-30d6026247aa",
  method: .delete,
  headers: [
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <token>"
  ]
).responseJSON { response in
  let status = response.response?.statusCode
}
using RestSharp;
 
var client = new RestClient("https://api.keygen.sh/v1/accounts/<account>");
var request = new RestRequest(
  "tokens/6a7562be-b302-43d2-a550-30d6026247aa",
  Method.DELETE
);
 
request.AddHeader("Accept", "application/vnd.api+json");
request.AddHeader("Authorization", "Bearer <token>");
 
var response = client.Execute(request);
using RestSharp;

var client = new RestClient("https://api.keygen.sh/v1/accounts/<account>");
var request = new RestRequest(
  "tokens/6a7562be-b302-43d2-a550-30d6026247aa",
  Method.DELETE
);

request.AddHeader("Accept", "application/vnd.api+json");
request.AddHeader("Authorization", "Bearer <token>");

var response = client.Execute(request);
import com.mashape.unirest.http.exceptions.*
import com.mashape.unirest.http.*
 
val res = Unirest.delete("https://api.keygen.sh/v1/accounts/<account>/tokens/6a7562be-b302-43d2-a550-30d6026247aa")
  .header("Authorization", "Bearer <token>")
  .header("Accept", "application/vnd.api+json")
  .asJson()
import com.mashape.unirest.http.exceptions.*
import com.mashape.unirest.http.*

val res = Unirest.delete("https://api.keygen.sh/v1/accounts/<account>/tokens/6a7562be-b302-43d2-a550-30d6026247aa")
  .header("Authorization", "Bearer <token>")
  .header("Accept", "application/vnd.api+json")
  .asJson()
import com.mashape.unirest.http.exceptions.*;
import com.mashape.unirest.http.*;
 
HttpResponse<JsonNode> res = Unirest.delete("https://api.keygen.sh/v1/accounts/<account>/tokens/6a7562be-b302-43d2-a550-30d6026247aa")
  .header("Authorization", "Bearer <token>")
  .header("Accept", "application/vnd.api+json")
  .asJson();
import com.mashape.unirest.http.exceptions.*;
import com.mashape.unirest.http.*;

HttpResponse<JsonNode> res = Unirest.delete("https://api.keygen.sh/v1/accounts/<account>/tokens/6a7562be-b302-43d2-a550-30d6026247aa")
  .header("Authorization", "Bearer <token>")
  .header("Accept", "application/vnd.api+json")
  .asJson();
#include <iostream>
#include <string>
#include <cpprest/http_client.h>
#include <cpprest/filestream.h>
 
using namespace std;
using namespace web;
using namespace web::http;
using namespace web::http::client;
using namespace utility;
 
http_client client("https://api.keygen.sh/v1/accounts/<account>");
http_request req;
 
req.headers().add("Authorization", "Bearer <token>");
req.headers().add("Accept", "application/json");
 
req.set_request_uri("/tokens/6a7562be-b302-43d2-a550-30d6026247aa");
req.set_method(methods::DELETE);
 
client.request(req)
  .then([](http_response res) {
    auto status = res.status_code();
  })
  .wait();
#include <iostream>
#include <string>
#include <cpprest/http_client.h>
#include <cpprest/filestream.h>

using namespace std;
using namespace web;
using namespace web::http;
using namespace web::http::client;
using namespace utility;

http_client client("https://api.keygen.sh/v1/accounts/<account>");
http_request req;

req.headers().add("Authorization", "Bearer <token>");
req.headers().add("Accept", "application/json");

req.set_request_uri("/tokens/6a7562be-b302-43d2-a550-30d6026247aa");
req.set_method(methods::DELETE);

client.request(req)
  .then([](http_response res) {
    auto status = res.status_code();
  })
  .wait();
curl -X DELETE https://api.keygen.sh/v1/accounts/<account>/tokens/6a7562be-b302-43d2-a550-30d6026247aa \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <token>'
curl -X DELETE https://api.keygen.sh/v1/accounts/<account>/tokens/6a7562be-b302-43d2-a550-30d6026247aa \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <token>'

Example response / 204 No Content

No content
No content

List 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.

Authentication

Bearer
required
An authentication token with privileges to view the resources.

URL Parameters

<account>
stringrequired
The identifier (UUID) or slug of your Keygen account.

Query Parameters

limit
integerdefault=10
A limit on the number of tokens to be returned. Limit must be a number between 1 and 100.
```
/v1/accounts/<account>/tokens?limit=25
/v1/accounts/<account>/tokens?limit=25
```
page
object<string, integer>
Object containing page size and page number. Page size must be a number between 1 and 100.
```
/v1/accounts/<account>/tokens?page[size]=15&page[number]=2
/v1/accounts/<account>/tokens?page[size]=15&page[number]=2
```

bearer

object<string, string>

Object containing the bearer's type and ID. Type can be product, license or user.

/v1/accounts/<account>/tokens?bearer[type]=license&bearer[id]=b18e3f3a-330c-4d8d-ae2e-014db21fa827
/v1/accounts/<account>/tokens?bearer[type]=license&bearer[id]=b18e3f3a-330c-4d8d-ae2e-014db21fa827

Returns

A 200 OK response will be returned along with a list of token objects.

Upon error, an errors object will be returned along with an HTTP status code indicating the type of error. When an error occurs, the data property will not be included.

Definition

https://api.keygen.sh/v1/accounts/<account>/tokens
https://api.keygen.sh/v1/accounts/<account>/tokens

Example request

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

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

const { data, errors } = await response.json()
import requests
import json
 
res = requests.get(
  "https://api.keygen.sh/v1/accounts/<account>/tokens?limit=15",
  headers={
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <token>"
  }
).json()
import requests
import json

res = requests.get(
  "https://api.keygen.sh/v1/accounts/<account>/tokens?limit=15",
  headers={
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <token>"
  }
).json()
import SwiftyJSON
import Alamofire
 
Alamofire.request("https://api.keygen.sh/v1/accounts/<account>/tokens?limit=15",
  headers: [
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <token>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<account>/tokens?limit=15",
  headers: [
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <token>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
using RestSharp;
 
var client = new RestClient("https://api.keygen.sh/v1/accounts/<account>");
var request = new RestRequest("tokens", Method.GET);
 
request.AddHeader("Accept", "application/vnd.api+json");
request.AddHeader("Authorization", "Bearer <token>");
 
request.AddParameter("limit", 15);
 
var response = client.Execute(request);
using RestSharp;

var client = new RestClient("https://api.keygen.sh/v1/accounts/<account>");
var request = new RestRequest("tokens", Method.GET);

request.AddHeader("Accept", "application/vnd.api+json");
request.AddHeader("Authorization", "Bearer <token>");

request.AddParameter("limit", 15);

var response = client.Execute(request);
import com.mashape.unirest.http.exceptions.*
import com.mashape.unirest.http.*
 
val res = Unirest.get("https://api.keygen.sh/v1/accounts/<account>/tokens")
  .header("Authorization", "Bearer <token>")
  .header("Accept", "application/vnd.api+json")
  .queryString("limit", 15)
  .asJson()
import com.mashape.unirest.http.exceptions.*
import com.mashape.unirest.http.*

val res = Unirest.get("https://api.keygen.sh/v1/accounts/<account>/tokens")
  .header("Authorization", "Bearer <token>")
  .header("Accept", "application/vnd.api+json")
  .queryString("limit", 15)
  .asJson()
import com.mashape.unirest.http.exceptions.*;
import com.mashape.unirest.http.*;
 
HttpResponse<JsonNode> res = Unirest.get("https://api.keygen.sh/v1/accounts/<account>/tokens")
  .header("Authorization", "Bearer <token>")
  .header("Accept", "application/vnd.api+json")
  .queryString("limit", 15)
  .asJson();
import com.mashape.unirest.http.exceptions.*;
import com.mashape.unirest.http.*;

HttpResponse<JsonNode> res = Unirest.get("https://api.keygen.sh/v1/accounts/<account>/tokens")
  .header("Authorization", "Bearer <token>")
  .header("Accept", "application/vnd.api+json")
  .queryString("limit", 15)
  .asJson();
#include <iostream>
#include <string>
#include <cpprest/http_client.h>
#include <cpprest/filestream.h>
 
using namespace std;
using namespace web;
using namespace web::http;
using namespace web::http::client;
using namespace utility;
 
http_client client("https://api.keygen.sh/v1/accounts/<account>");
http_request req;
 
req.headers().add("Authorization", "Bearer <token>");
req.headers().add("Accept", "application/json");
 
uri_builder uri("/tokens");
uri.append_query("limit", 15);
 
req.set_request_uri(uri.to_uri());
req.set_method(methods::GET);
 
client.request(req)
  .then([](http_response res) {
    auto data = res.extract_json().get();
  })
  .wait();
#include <iostream>
#include <string>
#include <cpprest/http_client.h>
#include <cpprest/filestream.h>

using namespace std;
using namespace web;
using namespace web::http;
using namespace web::http::client;
using namespace utility;

http_client client("https://api.keygen.sh/v1/accounts/<account>");
http_request req;

req.headers().add("Authorization", "Bearer <token>");
req.headers().add("Accept", "application/json");

uri_builder uri("/tokens");
uri.append_query("limit", 15);

req.set_request_uri(uri.to_uri());
req.set_method(methods::GET);

client.request(req)
  .then([](http_response res) {
    auto data = res.extract_json().get();
  })
  .wait();
curl https://api.keygen.sh/v1/accounts/<account>/tokens?limit=15 -g \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <token>'
curl https://api.keygen.sh/v1/accounts/<account>/tokens?limit=15 -g \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <token>'

Example response / 200 OK

{
  "data": [
    {
      "id": "6a7562be-b302-43d2-a550-30d6026247aa",
      "type": "tokens",
      "attributes": {
        "kind": "admin-token",
        "expiry": "2022-03-15T19:27:50.440Z",
        "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>"
          }
        },
        "bearer": {
          "links": {
            "related": "/v1/accounts/<account>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298"
          },
          "data": {
            "type": "users",
            "id": "a5a154d2-f026-40fa-bc8d-a7e3ca415298"
          }
        }
      }
    },
    …
  ]
}
{
  "data": [
    {
      "id": "6a7562be-b302-43d2-a550-30d6026247aa",
      "type": "tokens",
      "attributes": {
        "kind": "admin-token",
        "expiry": "2022-03-15T19:27:50.440Z",
        "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>"
          }
        },
        "bearer": {
          "links": {
            "related": "/v1/accounts/<account>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298"
          },
          "data": {
            "type": "users",
            "id": "a5a154d2-f026-40fa-bc8d-a7e3ca415298"
          }
        }
      }
    },
    …
  ]
}

linkTokens

linkTable of contents

linkThe token object

linkAttributes

linkdata.attributes.kind

Options

linkdata.attributes.token

linkdata.attributes.name

linkdata.attributes.expiry

linkdata.attributes.permissions

linkdata.attributes.maxActivations

linkdata.attributes.activations

linkdata.attributes.maxDeactivations

linkdata.attributes.deactivations

linkdata.attributes.created

linkdata.attributes.updated

linkRelationships

linkdata.relationships.account

linkdata.relationships.environment

linkdata.relationships.bearer

Example object

linkGenerate a token

linkAuthentication

linkBasic

linkURL Parameters

link<account>

linkAttributes

linkdata.attributes.name

linkdata.attributes.expiry

linkdata.attributes.permissions

linkMeta

linkmeta.otp

linkReturns

Definition

Example request

Example response / 201 Created

linkRetrieve a token

linkAuthentication

linkBearer

linkURL Parameters

link<account>

link<id>

linkReturns

Definition

Example request

Example response / 200 OK

linkRegenerate a token

linkAuthentication

linkBearer

linkURL Parameters

link<account>

link<id>

linkReturns

Definition

Example request

Example response / 200 OK

linkRevoke a token

linkAuthentication

linkBearer

linkURL Parameters

link<account>

link<id>

linkReturns

Definition

Example request

Example response / 204 No Content

linkList all tokens

linkAuthentication

linkBearer

linkURL Parameters

link<account>

linkQuery Parameters

linklimit

linkpage

linkbearer

linkReturns

Definition

Example request

Example response / 200 OK

Tokens

Table of contents

The token object

Attributes

data.attributes.kind

data.attributes.token

data.attributes.name

data.attributes.expiry

data.attributes.permissions

data.attributes.maxActivations

data.attributes.activations

data.attributes.maxDeactivations

data.attributes.deactivations

data.attributes.created

data.attributes.updated

Relationships

data.relationships.account

data.relationships.environment

data.relationships.bearer

Generate a token

Authentication

Basic

URL Parameters

<account>

Attributes

data.attributes.name

data.attributes.expiry

data.attributes.permissions

Meta

meta.otp

Returns

Retrieve a token

Authentication

Bearer

URL Parameters

<account>

<id>

Returns

Regenerate a token

Authentication

Bearer

URL Parameters

<account>

<id>

Returns

Revoke a token

Authentication

Bearer

URL Parameters

<account>

<id>

Returns

List all tokens

Authentication

Bearer

URL Parameters

<account>

Query Parameters

limit

page

bearer

Returns