Auth API

Authentication in Zesty.io is handled by the Auth API which issues a token that grants access to the Instances API, Accounts API, and Media API.

See complete Auth REST API Documentation

Roles and permission are managed by the Accounts API.

There are 2 types of authentication

• User
• Token-based

User Authentication

User authentication is done by providing a specific user account email and password combination. When authenticating as a user you are issued a session token. These are short lived 30 minute sessions that are extended whenever an authenticated action is taken. e.g. Saving content.

Ending a user authenticated session can be done by explicitly logging out. This ends the specifically referenced session. i.e. If you are logged in on another device it will not end that session.

Token-based Authentication

Token-based authentication is handled by the Accounts API. The issued access tokens are opaque, meaning they can not be parsed to determine their underlying properties such as; role, instance or owner. They are valid for 90 days from creation. In order to create an access token you must have an authenticated user session. Only users with Admin or Owner roles of an instance can issue a token.

Access tokens are assigned a role and roles are scoped to instances. Allowing them to take user like actions on the scoped instances. e.g. Creating, Publishing, etc... Tokens can be assigned existing system roles or a custom role defined on an instance. Custom roles are encouraged as they allow providing only the specific access a token needs. Reducing the potential impact of a leaked token.

Please Note: The value of access token will only be visible upon creation; please store it in a safe location.

Every access token is assigned a role which describes the permissions the token has against it's scoped instances.

Please Note: An access token is a secret which should be guarded carefully and every precaution taken to avoid leaking them. Simply having a token allows the holder that tokens scoped access.

If you want to find out the available roles on an instance use the Get Instance Roles endpoint which will return all the roles (and their IDs) associated with the Instance.

Access tokens are useful for automated API usage. e.g. CI/CD flows, migrating content, connecting third-party services, etc...

All actions taken with an access token is recorded by the AuditTrail API, similiar to users. AuditTrail logs will note the name of the token which was used for the action. These logs will not contain user information. Meaning if a token is used in a manual process, e.g. running a script, the log will not indicate the person who ran that process.

Revoking tokens can be done with the Accounts API. If a token is exposed it should be cycled by deleting the token and creating a new one.