MoxiWorks OAuth Authentication
OAuth Authentication
MoxiWorks provides an authentication service to allow clients to use MoxiWorks user accounts on their own properties. This can be useful to avoid managing end-user accounts and to provide a more seamless integration between MoxiWorks sites and client sites.
Authentication is provided with the industry-standard OAuth 2 protocol. OAuth 2 is used to get an access token for an individual user. That access token can then be used to look up information about the user, including a user’s unique identifier.
OAuth Credentials
OAuth 2 requires that clients have a client_id and a client_secret.
The client_id is an identifier for an individual client.
It doesn’t need to be kept secret.
The client_secret is a secret for proving to MoxiWorks that requests are coming from the client they claim to be.
It must not be shared with any party other than MoxiWorks.
That includes sending it to the end user’s browser and sharing with other third-party services.
Contact your account manager to get a client_id and client_secret for your application.
If there are third-party services that need access to MoxiWorks’ authentication service, contact your account manager to get a client_id and client_secret for them as well.
When you get your client_id and client_secret, you will also need to provide a list of valid redirect_uris.
These are the allowed locations to communicate information about the user’s authentication state back to clients.
Checking this list against a whitelist is a requirement of the OAuth 2 protocol.
The requirement exists to make sure that no information about end users is leaked to unauthorized parties.
A single redirect_uri is common, but more can be added if desired.
This list can be updated at any time.
Contact your account manager for assistance.
OAuth 2 Protocol
MoxiWorks authentication uses the Authorization Code Grant Oauth 2 flow.
This section describes the flow in detail, as used by MoxiWorks authentication. Most of this can be automated by using an appropriate OAuth 2 client library.
Client Initiation
The authorization code grant begins with the client deciding to authorize the end user.
| Attribute | Type | Remark | Required |
|---|---|---|---|
| client_id | String | The client_id assigned to this client |
required |
| redirect_uri | String | The location to redirect the end user’s user agent to after authenticating the end user | required |
| response_type | String | This field must always be set to code |
required |
| state | String | If provided, this value will be in the response to the redirect_uri. Its purpose is to allow sending per-request data without changing the redirect_uri. |
optional |
| company_uuid | String | If provided, this value gives a hint for the authorization system about what brokerate agents logging in will be from. This is used to ensure agents have the correct sign-in experience, if required. If it’s not provided, it will be inferred from the client_id. |
optional |
| moxi_works_company_id | String | Another method to specify agent sign-in experience. Serves the same purpose as company_uuid, but takes the same format company id as the rest of the API uses. Will be ignored if company_uuid is also provided. |
optional |
MoxiWorks will authenticate the user and redirect their user agent to the redirect_uri specified.
When the user agent requests the redirect_uri, it will have one or two additional query arguments provided.
It will have a parameter named code which contains the authorization code.
If the original request contained a state parameter, the redirect will also contain a state parameter with the same value.
Access Token Request
Once the client has an authorization code, they can exchange it for an access token and a refresh token.
| Attribute | Type | Remark | Required |
|---|---|---|---|
| client_id | String | The client_id assigned to this client |
required |
| client_secret | String | The client_secret assigned to this client |
required |
| code | String | The authorization code obtained in the previous step | required |
| grant_type | String | This field must always be set to authorization_code |
required |
| redirect_uri | String | This must exactly match the redirect_uri as provided in the request to get the authorization code |
required |
This call responds with a JSON object containing the following values:
| Attribute | Type | Remark |
|---|---|---|
| access_token | String | The access token. |
| token_type | String | The type of the access token. This will always be bearer. |
| expires_in | Number | The length of time the access token is valid for, in seconds. |
| refresh_token | String | The refresh token for getting a new access token. |
| created_at | Number | The POSIX timestamp at which this access token was issued. |
Refresh Token Request
Access tokens are short-lived. For most uses of authentication, this is sufficient - getting a unique identifier for the user at the time they authenticate is all that is needed. In some cases, the client will wish to perform subsequent lookups of end user information, beyond the lifetime of the access token. When a client wishes to do this they can use the refresh token to get a new access token.
| Attribute | Type | Remark | Required |
|---|---|---|---|
| client_id | String | The client_id assigned to this client |
required |
| client_secret | String | The client_secret assigned to this client |
required |
| refresh_token | String | The refresh token previously obtained for this end user | required |
| grant_type | String | This field must always be set to refresh_token |
required |
This call responds with a JSON object of a form identical to the previous means of getting an access token.
Obtaining End User Profiles
An access token can be used to get information about an end user.
The request is gated by the presence of an OAuth 2 access token.
To send the access token in the request, add an Authorization HTTP header with a value of Bearer <access_token>.
If the access token has expired or is otherwise invalid, the server responds with a 401 Unauthorized status and the WWW-Authenticate header specifying error="invalid_token".
If the access token is valid, but the user isn’t authorized to authenticate with the client, the server responds with a 401 Unauthorized status and the WWW-Authenticate header specifying error="user_not_authorized".
If the access token was valid, a JSON object is returned:
| Attribute | Type | Remark |
|---|---|---|
| display_name | String | The end user’s display name |
| username | String | A unique (mutable) identifier for the end user |
| user_id | String | A unique (immutable) identifier for the end user |
| String | Deprecated - this might be the value from either email_primary or email_display. Use one of those fields for better control over what data is being used. | |
| email_primary | String | The end user’s primary email address, used for messaging from MoxiWorks |
| email_display | String | The end user’s display email address, advertised to customers |
| company_name | String | The name of the company the end user works at |
| external_id | String | A unique identifier for the end user provided by the user’s company |
More fields may be added to this in the future. Consumers of this data should not fail if more fields are present in the result.