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 an environment, 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, environment 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. Persistent 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 license 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.
env Authenticated environments may access resources for their account that are within that particular environment. All resources that are returned will be scoped to the environment, e.g. when an environment makes a request to list all licenses, only the licenses within the environment 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 during creation or via update. You can also update per-resource default permission sets via your account settings.

Special notes

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

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

  • All resources intersect their resource's allowed permission set. For example, a license can never have the policy.create permission.

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

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