Admin APIs

Everything that can be done in Admin UI (and a little bit more) can also be done through API calls. This makes it possible to embed administration into other applications and completely customize the UI for administration.

Some of the APIs are limited to a single tenant, for example it is only possible to handle users for a single tenant. The following API:s are bound to a tenant:

  • Person
  • Users
  • Groups
  • External systems
  • Organisations (depending on permissions)

For external systems and users that have the special permission (manage organisations) to configure tenants it is possible to control which tenant each API call should be handled for by passing the X-IRM-TenantId HTTP Header with the unique identity (UUID) as value.

Within the Users APIs there are special /me endpoints which requires an access token of an actual end-user to be used. Since they represent an actual user, there is no need to pass any Tenant Id.

All other APIs are configuration APIs and instead requires very specific permissions to be used.

Important information about the unique identifiers (GUID:s)

Many APIs allows you to pass a unique identifier in the form of a GUID (UUID), but we recommend you to not do that and instead let Authway create an optimized Id, which is returned in all responses to create APIs. If you need to pass the Id from your code we strongly recommend you to use an algorithm that creates identifiers optimized for the underlying database, or else the performance of the system will be negatively impacted. We can provide you with such algorithm for SQL Server.

Errors from the APIs

We try to use reasonable status codes for different situations in the API. When we return a body with error information, the body follows the Problem Details for HTTP APIs (RFC 7807) standard.

Status Code Description Details
400 Errors in the provided data. This will always have a problem details body with more information about the error.
401 Failed to authenticate the call.
403 The user or client calling the API is missing the required permission.
404 The URL is not matching any API or the id:s in the URL does not match any existing object. This will often have a problem details body with more information about the error.
500 An internal server error. Of course we make our best to not end up with a 500 error, but it could for example be a dead lock situation or that we for some reason couldn’t reach the database at all and so on.
501 Not implemented or supported. Very uncommon, but there are scenarios where you can call the API with values that are not incorrect, but still not supported. Another situation is when trying to use an API for a feature that is not part of the bought service. In those cases, we have chosen to give a 501 instead of a 400. This could happen during development, but should never be a case in production if the consumption of the API have been tested correctly, but 400 errors could exist in production and be caused by end-user data.
503 Infrastructure problem. Most likely temporarily.