NAV Navbar
Logo
JSON .Net Ruby PHP HTTP

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
email String The end user’s email address
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.