Skip to main content

Authenticating with sso

If you want to start using Aircall ecosystem, you would need to authenticate your agents, and one of the classic ways of doing so, is by using sso strategy.

{
  "type": "AUTH.SSO",
  "payload": {
    "code": "String!",
    "redirectUrl": "String!"
  }
}
note

You don't need to initialize the authentication service in order to use this event.

Usage​

When the user tries to use the integration for the first time, they should be asked to provide their credentials in order to authenticate and start using the app.

This is possible by sending the AUTH.SSO and waiting for AUTH.SSO_FULFILLED or AUTH.SSO_REJECTED depending on whether the credentials are correct or not.

{
  "type": "AUTH.SSO",
  "payload": {
    "code": "06fff5b1-0ddf-4162-805e-1e74762000d4",
    "redirectUrl": "https://dashboard.aircall-staging.com/login/sso"
  }
}
danger

It's VERY important that you make sure that this event is ONLY sent to the bus 🚌 iframe instead of sending it to all the iframes that are listening for messages coming from outside.

Successful authentication​

When everything goes fine, you will receive a AUTH.SSO_FULFILLED event:

{
  "type": "AUTH.SSO_FULFILLED",
  "payload": {
    "credentials": "MigratedCredentials | LegacyCredentials",
    "currentUser": "User",
    "company": "Company"
  }
}

Something went wrong​

If something bad happens, you will receive a AUTH.SSO_REJECTED event:

{
  "type": "AUTH.SSO_REJECTED",
  "payload": {
    "error": "Error"
  }
}

The error here, will correspond to whatever the backend service returns.

Reference​

  • code: code recieved after redirecting to id.aircall for SSO initiation
  • redirectUrl: redirect url
/**
 * For the vast majority of Aircall users, you will receive this type of credentials.
 */
interface MigratedCredentials {
  idToken: string;
  refreshToken: string;
}
// For some specific users, you might receive what we call a legacy token.
interface LegacyCredentials {
  legacy_token: string;
}

Both idToken and legacy_token allows you to interact with our backend APIs.

One difference exist though, is that idToken expires every 15 minutes and legacy_token never expires.