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.

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 on our Ent tiers. Standard tiers use defaults.

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.

admin env 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
engine.read ✅***
entitlement.create
entitlement.delete
entitlement.read
entitlement.update
environment.create
environment.delete
environment.read
environment.tokens.generate
environment.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.owner.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.users.attach ✅*
license.users.detach ✅*
license.validate ✅***
machine.check-out ✅**
machine.create ✅**
machine.delete ✅**
machine.group.update
machine.heartbeat.ping ✅**
machine.heartbeat.reset
machine.owner.update
machine.proofs.generate ✅**
machine.read
machine.update ✅** ✅**
metric.read
package.create
package.delete
package.read ✅***
package.update
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.package.update
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.