TraitWare Login APIs (OAuth)

Posted on April 20, 2022

This lists TraitWare’s OAuth endpoints. They can be used to provide OAuth tokens to applications that support the OAuth 2.0 spec. To begin, create an OAuth application in the TraitWare Admin Console. You will obtain the needed client_id and client_secret during the setup of the application.

Depending on the integration you may only need to copy/paste a few values.

client_id and client_secret – from your TraitWare application

Authorization Endpoint: https://api.traitware.com/customer-api/v1/oauth2/authorization

Token Endpoint: https://api.traitware.com/customer-api/v1/oauth2/token

For more manual integrations, please see the documentation that follows.

TraitWare Endpoints

Authorization Endpoint

Headers for getting response values for login attempt:
[Content-Type: application/json]

No headers for using TraitWare hosted login page.

Request: GET https://api.traitware.com/customer-api/v1/oauth2/authorization

QueryString Params:
    ?client_id=CLIENT_ID    # from the TCC for this application (required)
    &response_type=code     # specify this parameter as 'code'
    &redirect_uri=REDIRECT_URI  # redirect URI to the Client (optional - must be url-encoded)
    &state=CSRF_VALUE       # generated by Client and compared at redirection endpoint

Successful Response: HTTP Status 3xx (redirected to TraitWare login)

Unsuccessful Response: HTTP Status 4xx or 5xx

Description: Endpoint where the OAuth implementation or the "Login with TraitWare" button links to. 
             Specific error information will be reported to the Redirection Endpoint.

Token Endpoint

Header Content Types supported: application/json, application/x-www-form-urlencoded

[Content-Type: application/json]

Request: POST https://api.traitware.com/customer-api/v1/oauth2/token
{
    "client_id":  { type: String, required: true },     # from the TCC for this application
    "client_secret": { type: String, required: true },  # from the TCC for this application
    "code": { type: String, required: true },           # AUTHORIZATION_CODE
    "grant_type": "authorization_code" { type: String, required: true }, # must specify the grant type
}

Successful Response: (Content-Type: application/json)
{
    "access_token": { type: String, required: true },
    "timeout": { type: Integer, required: true },
    "state": { type: String, required: true }
}

HTTP Status 200

Unsuccessful Response: (Content-Type: application/json)
{
    "error": { type: String, required: true, enum: ERROR_TYPE },
    "state": { type: String, required: true }
}
HTTP Status 4xx/5xx

ERROR_TYPE:

    invalid_request
        The request is missing a required parameter, includes an
        unsupported parameter value (other than grant type),
        repeats a parameter, includes multiple credentials,
        utilizes more than one mechanism for authenticating the
        client, or is otherwise malformed.

    invalid_client
        Client authentication failed (e.g., unknown client, no
        client authentication included, or unsupported
        authentication method).  The authorization server MAY
        return an HTTP 401 (Unauthorized) status code to indicate
        which HTTP authentication schemes are supported.  If the
        client attempted to authenticate via the "Authorization"
        request header field, the authorization server MUST
        respond with an HTTP 401 (Unauthorized) status code and
        include the "WWW-Authenticate" response header field
        matching the authentication scheme used by the client.

    invalid_grant
        The provided authorization grant (e.g., authorization
        code, resource owner credentials) or refresh token is
        invalid, expired, revoked, does not match the redirection
        URI used in the authorization request, or was issued to
        another client.

    unauthorized_client
        The authenticated client is not authorized to use this
        authorization grant type.

    unsupported_grant_type
        The authorization grant type is not supported by the
        authorization server.

Description: Endpoint that the customer web server calls after receiving the authorization_code 
             via the Redirection Endpoint call. This is a call to TraitWare's server to exchange
             the authorization_code for an access_token via a secure channel, server-to-server, 
             using the client_secret. 

Client Browser Login

Optional depending on use – This provides a button to initiate a TraitWare login on a client page. Some OAuth clients may already provide this functionality independently, or you may want to create your own.

Login Page Snippets

For the client site login, the following needs to be added to the HTML in the login page where a “Login with TraitWare” button will appear:

<div id="TraitwareLoginButton"></div>

This javascript needs to be added to the bottom of that page:

<script type="text/javascript">
TW = Object(); 
TW.clientId = "CLIENT_ID";
TW.state = "STATE";
</script> 
<script src="https://api.traitware.com/customer-api/v1/twlogin.js"></script>

Be sure to substitute CLIENT_ID and STATE with your own values during page render. CLIENT_ID is your application’s client_id available in the Traitware Customer Console. The STATE value is generated by your web server as a Cross Site Request Forgery (CSRF) protection and should be compared in your Redirection Endpoint to ensure the request was originated by your server.