Getting started with Authress

1. Signing up

Before you can use Authress API, you need to create an account with us.

During the signup process, we’ll ask you to login with one of the federated login providers - Google or Microsoft. If you want to login using your company’s SSO (Single Sign On) solution, you’ll be able to set that up in your Settings after the initial sign up.

2. Service clients and API keys

Authress is an API that your software services will call at runtime to determine whether a given user is allowed to perform a particular action.

In order to protect your data, your services will need to authenticate with Authress. This is done through API keys. Register your service clients in Management Portal - this will also let you generate the API keys. You can register as many service clients as you need.

3. Integrating your software with Authress

Once you’ve registered your service client, integrating with Authress is easy. You can either call our APIs directly, or download an SDK to make things even simpler.

Authress has SDKs for the most common languages. If we don’t have the one you are looking for, let us know and we’ll work on releasing it.

4. Defining your user roles

Authress doesn’t know how your software works, nor it wants to. But it does need to know about your permissions.

In Authress, permissions are grouped into roles. Think of roles as sets of permissions that are often granted together. For example, a document owner may be able to “read”, “write”, and “delete” the document, while a reviewer would be only able to “read” and “suggest”.

You may already have a model of your user personas and typical actions associated with each of them - these will likely correspond to your roles. If your model is incomplete, or you’re not ready to think about it just yet, you may use the built-in roles and expand them later as your software evolves. You can define your roles, as well as see the built-in ones in Management Portal.

Later on, you’ll be applying these roles to specific resources and users through the access records, described below.

5. Configuring user permissions

Authress authorizes your users based on the permissions you configure. This is done through access records.

Whenever a new resource is created in your software (e.g., user creates a new document), you create a new access record in Authress by calling respective API and specifying the roles. You can also do this manually in Management Portal.

6. Connecting your identity providers

Instead of resolving your user identity before calling Authress each time, you may want to delegate this responsibility to Authress. To do that, you will simply pass the user JWT along with your calls.

You can use Authress out of the box with any identity provider that uses OIDC compliant JWTs (such as Google, Auth0 or Okta). Grab the JWT from your preferred provider and paste it in Management Portal to set up the integration.

7. Using Authress to determine user permissions

Now that everything is set up, each time your software needs to decide whether the user should be allowed to perform certain actions on a given resource, you simply make an API call to Authress. You’ll get back either a 200 (meaning user has permissions) or 404 (meaning user doesn’t have permissions).

Take a look at the full API documentation to see what else is possible.