menu
Select programming language for code examples

linkAuthorization

Keygen uses a RBAC (Role-Based Access Control) system. Access to certain resources is dependent upon a token bearer's role. Most of the time you will be authenticating as a license, or as a user, which will allow access to a small subset of resources available to your account. Typically, this authentication is done client-side.

In other cases, as when you are using Keygen server-side, you may be authenticating as a product, or even an admin. In these cases, you will have access to a wider range of resources.

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, in CI/CD, or locally via the CLI.

Most API resource endpoints are automatically scoped according to the authenticated token bearer. For example, listing all licenses while authenticated as a product will only list licenses associated with that particular product. Likewise, when listing all licenses as a user, only licenses belonging to that user will be returned.

Throughout the docs, some resource attributes and relationships may be marked with a "protected" badge. This means that the attribute or relationship is only available to be set while authenticated as an admin of the account, or a product that owns the resource.

Likewise, attributes and relationships marked with a "read only" badge cannot be modified directly. These are typically timestamps and computed attributes.

Attempting to access resources that the bearer does not have access to will respond with a 403 forbidden error. Peristent 403s may result in rate limiting.

linkTable of contents

  1. Quick summary of roles
  2. Permission matrix

linkQuick summary of roles

Below is a quick summary of the different authorization roles, with default permissions:

Role Summary
anon Unauthenticated users can create a new user profile (unless your account is protected), access open/public releases, and validate license keys using the validate-key action. No other endpoints are accessisible to unauthenticated users.
user Authenticated users may access certain resource endpoints, but all resources that are returned will be scoped to their user profile, e.g. when a user makes a request to list all licenses, only the licenses which are associated with their user profile will be returned.
license Authenticated licenses may access certain resource endpoints through license key authentication or via activation tokens, but all resources that are returned will be scoped to the license, e.g. when a license makes a request to list all machines, only the machines that are associated to the license will be returned.
product Authenticated products may access resources for their account that are associated with that particular product. All resources that are returned will be scoped to the product, e.g. when a product makes a request to list all licenses, only the licenses which are associated with the product will be returned.
admin Authenticated admin users may access all resources for their account.

linkPermission matrix

Below is a complete default permission matrix for each role. Keep in mind that resources are also scoped to the current bearer, according to role.

Looking to customize things? Permissions can be assigned per-resource and per-token on our Ent tiers. Standard tiers use defaults.

Special notes

  • Licenses inherit and intersect their user's permissions. For example, if a user had license.read and user.read permissions, the user's licenses cannot have the machine.create permission. A license's permissions are a subset of its user's. This does not apply to licenses without a user.

  • Tokens inherit and intersect their bearer's permissions. For example, if a license had license.validate and license.read permissions, its tokens cannot have user.read permissions. A token's permissions are a subset of its bearer's.

admin product license user anon
account.analytics.read ✅
account.billing.read ✅
account.billing.update ✅
account.plan.read ✅
account.plan.update ✅
account.read ✅ ✅ ✅* ✅*
account.subscription.read ✅
account.subscription.update ✅
account.update ✅
admin.create ✅
admin.delete ✅
admin.invite ✅
admin.read ✅
admin.update ✅
arch.read ✅ ✅ ✅ ✅ ✅***
artifact.create ✅ ✅
artifact.delete ✅ ✅
artifact.read ✅ ✅ ✅ ✅ ✅***
artifact.update ✅ ✅
channel.read ✅ ✅ ✅ ✅ ✅***
constraint.read ✅ ✅ ✅ ✅
entitlement.create ✅
entitlement.delete ✅
entitlement.read ✅ ✅ ✅ ✅
entitlement.update ✅
event-log.read ✅
group.create ✅ ✅
group.delete ✅ ✅
group.licenses.read ✅ ✅
group.machines.read ✅ ✅
group.owners.attach ✅ ✅
group.owners.detach ✅ ✅
group.owners.read ✅ ✅ ✅ ✅
group.read ✅ ✅ ✅ ✅
group.update ✅ ✅
group.users.read ✅ ✅ ✅
key.create ✅ ✅
key.delete ✅ ✅
key.read ✅ ✅
key.update ✅ ✅
license.check-in ✅ ✅ ✅ ✅
license.check-out ✅ ✅ ✅ ✅
license.create ✅ ✅ ✅**
license.delete ✅ ✅ ✅**
license.entitlements.attach ✅ ✅
license.entitlements.detach ✅ ✅
license.group.update ✅ ✅
license.policy.update ✅ ✅ ✅**
license.read ✅ ✅ ✅ ✅
license.reinstate ✅ ✅
license.renew ✅ ✅ ✅**
license.revoke ✅ ✅ ✅**
license.suspend ✅ ✅
license.tokens.generate ✅ ✅
license.update ✅ ✅
license.usage.decrement ✅ ✅
license.usage.increment ✅ ✅ ✅ ✅**
license.usage.reset ✅ ✅
license.user.update ✅ ✅
license.validate ✅ ✅ ✅ ✅ ✅***
machine.check-out ✅ ✅ ✅ ✅**
machine.create ✅ ✅ ✅ ✅**
machine.delete ✅ ✅ ✅ ✅**
machine.group.update ✅ ✅
machine.heartbeat.ping ✅ ✅ ✅ ✅**
machine.heartbeat.reset ✅ ✅
machine.proofs.generate ✅ ✅ ✅ ✅**
machine.read ✅ ✅ ✅ ✅
machine.update ✅ ✅ ✅** ✅**
metric.read ✅
platform.read ✅ ✅ ✅ ✅ ✅***
policy.create ✅ ✅
policy.delete ✅ ✅
policy.entitlements.attach ✅ ✅
policy.entitlements.detach ✅ ✅
policy.pool.pop ✅ ✅
policy.read ✅ ✅ ✅* ✅*
policy.update ✅ ✅
process.create ✅ ✅ ✅ ✅**
process.delete ✅ ✅ ✅ ✅**
process.heartbeat.ping ✅ ✅ ✅ ✅**
process.read ✅ ✅ ✅ ✅
process.update ✅ ✅ ✅ ✅**
product.create ✅
product.delete ✅
product.read ✅ ✅ ✅* ✅*
product.tokens.generate ✅
product.update ✅ ✅
release.constraints.attach ✅ ✅
release.constraints.detach ✅ ✅
release.create ✅ ✅
release.delete ✅ ✅
release.download ✅ ✅ ✅ ✅ ✅***
release.publish ✅ ✅
release.read ✅ ✅ ✅ ✅ ✅***
release.update ✅ ✅
release.upgrade ✅ ✅ ✅ ✅ ✅***
release.upload ✅ ✅
release.yank ✅ ✅
request-log.read ✅
token.generate ✅ ✅ ✅
token.read ✅ ✅ ✅ ✅
token.regenerate ✅ ✅ ✅ ✅
token.revoke ✅ ✅ ✅ ✅
user.ban ✅ ✅
user.create ✅ ✅ ✅**
user.delete ✅
user.group.update ✅ ✅
user.invite ✅
user.password.reset ✅ ✅
user.password.update ✅ ✅
user.read ✅ ✅ ✅ * ✅
user.second-factors.create ✅ ✅
user.second-factors.delete ✅ ✅
user.second-factors.read ✅ ✅
user.second-factors.update ✅ ✅
user.tokens.generate ✅ ✅
user.unban ✅ ✅
user.update ✅ ✅ ✅
webhook-endpoint.create ✅ ✅
webhook-endpoint.delete ✅ ✅
webhook-endpoint.read ✅ ✅
webhook-endpoint.update ✅ ✅
webhook-event.delete ✅
webhook-event.read ✅ ✅
webhook-event.retry ✅

* These permissions are disabled by default, for backwards compatibility reasons.

** These permissions are effective only when the account is unprotected.

*** These permissions are effective on products with an OPEN distribution strategy.