Skip to main content

Granting access to users

Access Records

Authorization checks verify a user's permissions to a particular resource. A check always includes user, resource, and permission. So the creation and assignment of permissions must also include these three same notions. Access records are the place in Authress where a user gets permissions.

Access records combine permissions on resources to make statements, and access records statements are assigned to a user list. A user user_id_sub might have star (*) access to all documents in an organization /organizations/org1/documents/*. (For brevity, in the following cases /organizations/org1 is usually omitted.)


Instead of permissions access records use roles. The only difference between roles and permissions is that roles are a bag of permissions. They do not specify resources. Assigning a role for a resource to a user in an access record gives that user all the permissions in the role to the resources in the statement.


The list of all users will gain access via the roles and resources. Subsets of users are not supported. To give different users different access, create separate access records, one for each list of valid statements.


To prevent unnecessary proliferation of access records, records support multiple statements. Statements are disjoint and do not affect each other. The roles in a statement apply to the resources in the statement, but not to other statements. This makes it easy to assign different levels of permissions to different resources all for the same users in the same access record.

multiple access record statements

Cascading resources

Access records resources always imply cascading permissions to sub-resources. When a permission documents:read is assigned to a user for resource /documents/*, this implies they also have documents:read to /documents/A and /documents/B/sub-documents/C/metadata. This is important when modeling resource permissions. If cascading permissions should not apply in a circumstance, then take the action to split the model. For instance, if metadata access to sub-resources should not be cascaded from documents, then split /documents/*/metadata to /metadata/* when assigning and checking permissions.

Fetching user resources

Due to the nature of cascading resources, it becomes easy to get all the sub-resources. GET /users/{userId}/resources?resourceUri=/documents/ will return all the resources that are sub-resources of documents. In the document repository, it is equivalent to an ls or list on the top level.

When to create an access record

Access records should be created or updated whenever there is a change to any user's permission in your system. For every action in Authress an authorization check is may, and for every resource created a record is generated. This way permissions always stay flexible. Authress is optimally designed to make this very effective and performant. In most cases this amounts to the equivalent of a database write.

Creating new application resources

When a new resource is generated in your application, only the service that owns the resource has access by default. To allow the user to access the resource they just created, create an access record. Most frequently a user might already have access to create a resource. For instance, if a user has a role which contains documents:* for resource /org/{orgId}/documents, then the user already has access to all documents scoped permissions for ever document in the organization. Creating an additional record in this case may not be valuable. Records created through this process are considered resource based records.

[Optional] It can be valuable to specify the id of a new access record to match the resource being created, and store additional users/resources in this resource as the permissions change. This is completely optional, as authorization checks do not directly use access records, it does not matter how access records users permissions are organized. Access record organization is completely up to the admins of Authress.

Editing an access record

Most of the general cases of access record management happen through your application service calls via the Authress SDKs. However, the Authress UI offers a full feature set to create and manage user permissions as well.

User management of permissions

Permissions may be shared between users and user managed by creating or editing existing access records. In these cases to change the permissions in an access record generally the user must at least have Grant, however since Grant is frequently used, Delegate permission access for most actions will be required.

updating access record with missing permissions

What is a record admin?

As with all resources, permissions to change Authress related resources are scoped to Authress:RESOURCE. For access records, editing and assigning permissions is easier by assigning record admins. These admins are not given any permission in the record other than to change the record itself. A record admin must Still have necessary Grant and Delegate permissions that in the record. A record admin may change a record, but in a way which would violate their own permissions.

Handling record limits

Records should be considered limited in size. Records that have more than 100 users or 100 statements/resources are generally not permitted and will be restricted by the API. When designing a system to use access records compare the cardinality of the size of the resource set with the allowed size of a access record. If the access record is larger by a magnitude, then there is safety in performing the action. If your resource set is unbounded, then unique generation of resource records is required. Resource records are free with the usage of the API, so the only benefit to limiting resource records is for ease of manual management, not for performance of Authress or your application. In most cases, more resource records are faster than larger ones. (More information is available in the Billing, caching and rate limiting article)