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.

Events API

Authway has events for many of the things that happens in the service. You can tap into these events and write your own logic by registering a webhook or by using our Event API. Note that webhook feature is only available in the Enterprise edition of the service.

Common Properties in all events

Each event payload also contains properties unique to the event. You can find the unique properties in the individual event documentation.

IpAddressLocation Properties

Depending on environment and configuration some events will include location information based on the IP address. Sources for this information can also be different when hosting your-self compared to Authway IDaaS.

When an IpAddressLocaiton exist in the event, we garuantee that the CountryCode and Country is set, but the other properties will depend on information availability in the source.

Available Events

Organisation Events

To retrieve all organisation events you use the topic “organisation”.

• OrganisationCreated
• OrganisationUpdated
• OrganisationDeleted
• OrganisationClaimAdded
• OrganisationClaimRemoved
• TrustedDomainAdded
• TrustedDomainRemoved

Person Events

To retrieve all organisation events you use the topic “person”.

• PersonCreated
• PersonUpdated
• PersonDeleted

User Events

To retrieve all organisation events you use the topic “user”.

• UserCreated
• UserUpdated
• UserDeleted
• UserInvited
• UserLoginAdded
• UserLoginRemoved
• UserUsernameChanged
• UserPasswordChanged
• UserPasswordRemoved
• UserRoleAdded
• UserRoleRemoved
• UserSignInAssociated
• UserSignedIn
• UserSignedOut
• UserSignInFailed
• UserLockedout
• UserUnlocked
• UserConfirmedEmail
• UserConfirmedPhoneNumber
• UserClaimAdded
• UserClaimRemoved

Organisation module Events

To retrieve all organisation module events you use the topic “organisationmodule”.

• ModuleActivatedForOrganisation
• ModuleInactivatedForOrganisation
• ModulePayedForOrganisation
• ModuleUnpayedForOrganisation

Module Events

To retrieve all module events you use the topic “module”.

• FunctionalityDeleted
• ModuleWentOffline
• ModuleWentOnline

Webhooks

Authway uses webhooks to automatically notify your application any time certain changes happens in Authway.

Webhooks can be set up per event stream, where a stream is responding to a major information object for examples person, user or organisation. It is possible to set up multiple webhooks for a single stream and naturally it is possible to set up webhooks for different streams. The webhooks are grouped in a webhook system. The webhook system will typically be one for the consuming application. If one webhook is failing for a system, all webhooks for that system is stopped, which can affect how you choose to group your webhooks.

By default you will only be able to receive events that is owned by the same tenant as the Webhook is registered for.

Handling events

Choose event to recieve

When configuring a webhook, you can use the API to choose which events will send you payloads. This is done by setting a topic to the stream or a specific event. Only subscribing to the specific events you plan on handling limits the number of HTTP requests to your application. You can also subscribe to all current and future events. By default, webhooks are only subscribed to the future events. You can change the topic at any time, but for an existing webhook, it will only affect future events.

Advanced Topics

A topic is flexible and you can combine more than one “thing” in a topic by separating each identifier with “,”. For example:

Respond immediately to events

When receiving an event to your webhook, it is strongly recommended to respond with a 200 Ok (or another 2XX status code) as quickly as possible. Failing to do so might trigger re-tries which can increase the load of your application more than necessary.

A common pattern to handle webhook events effectivly is to add the event body on a message queue and immediately respond with a success status code. The internal queue can then be processed by a background worker.

Re-tries of failed events

For a configured webhook we guarantee that subscribed events are delivered at least once and in correct order (per webhook). If we get a timeout, a network failure or if we receive a response with status code 408 or any 5XX we’ll retry to send the payload again. Authway uses an exponential backoff scheme when doing re-tries and if all re-tries fails the webhook system will stopped. When this happens we will notify you by the registered e-mail address. It is your responsibility to re-start a stopped webhook system when your application is ready to handle the events again.

If Authway is causing the failure, we will also re-start the webhook system after we have corrected the issue.

Ignoring duplicate events

It is possible to receive the same event more than once, so we recommends that you handle webhook events using idempotent operations. One way of doing this is logging the EventId of the events that you have processed and ignoring subsequent requests with the same EventId.

Order of events

Authway guarantees that events within a webhook is delivered in the same sequence that they are happening. Between webhooks there are no guarantees of ordering, so your logic should handle cases where events are delivered out of order. If you create separate webhook systems, the ordering of the events between these systems is also not guaranteed.

Securing webhooks

Validating events are from Authway

Since the webhook receiver is available on the public Internet it is very important that you validate the incoming request before processing it. We recommend that you start by checking that all three custom HTTP headers are available. From security perspective the X-IRM-Signature header is the important one. Use your secret (that you used during registration) to calculate a HMAC-SHA256 signature of the received body.

C#:

using System;
using System.Security.Cryptography;
using System.Text;

class WebhookSignature
{
   public static string ComputeSignature(string data, string secret)
   {
       HMACSHA256 hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
       byte[] stringBytes = Encoding.UTF8.GetBytes(data);
       byte[] hashedValue = hmac.ComputeHash(stringBytes);
       return Convert.ToBase64String(hashedValue);
   }

   public static void Main (string[] args)
   {
       Console.WriteLine(ComputeSignature("messageBody", "apikey"));
   }
} 

PHP:

function compute_signature($data, $secret) {
    return base64_encode(hash_hmac('sha256', $data, $secret, true));
}

echo(compute_signature('messageBody','apikey')); 

Require authentication

Authway supports Basic authentication when calling your webhook. You provide the username and password when registering the webhook.

Obfuscating webhook URL

A minor improvment in the security of webhooks is to make the endpoints harder to guess. This can be done by adding a series of random numbers and letters to your endpoint URL. For example https://api.yourapplication.com/webhooks/j490smlkfs034jld94jlae045 is harder to guess than https://api.yourapplication.com/webhooks.

Testing Webhooks

It is not necessary for you to immediately create och deploy a service that can receive webhook payloads. Instead we recommend you to start with ay of the service on Internet that allows you to receive HTTP POST calls, for example https://webhook.site/. That service makes it really easy to get something up and running, and you can easily see the webhook payload directly in your browser.

To start receiving webhooks you must first start (activate) the webhook system by calling api/systems/{systemId}/start. Trigger some events in the source system and you should soon see POST arriving in the browser.

You can also stop the pushing of new events by calling api/systems/{systemId}/stop. If you want to simulate that the system have been stopped because of a failure you can use the same API. Use the source system to create some more events and then start the system again, and you should see all events be posted until it catches up to the last existing event.

You can also get information about the last date/time and event id that have been successfully posted to your webhook by making a get request to api/systems/{systemId}.

Exposing your Local Machine to the Internet

Since all webhooks are pushed over Internet, you’ll have to expose your local machine somehow, if you want to receive webhooks during development. We recommend that you use for example Ultrahook or ngrok to do that.

After configuring a service you’ll have to reconfigure your webhook system to receive payloads on your new URL.