Making Authenticated API Requests

All Yapster API requests must include an Authorization HTTP Header using the Token authentication scheme with a valid authentication token value as returned by one of the following authentication methods.

Thus, all requests expect those below will be of the form:

$ curl -H "Authorization: Token <auth token value>" <api endpoint url>

Username & Password Authentication

Path	`/api/unified-login`
Method	`GET`
Response Type	`application/json`

Request Parameters

The request must include the following HTTP query parameters:

Name	Value
id	the users registered email address
password	the (plaintext) password

Example Request

Authenticating as the user with email address ‘user@example.com’ and password ‘abcd1234’:

$ curl \ 
  -X GET \ 
  -H 'Accept: application/json' \
  'https://devapi.yapsterchat.com/api/unified-login?id=user%40example.com&password=abcd1234'

Note that due to being passed as query parameters the username and password must be URL escaped (‘@’ becomes ‘%40’.)

Response

A successful response will be a JSON document consisting of:

{
  "login-status": "password-ok",
  "auth-user": {
    "id": "<user UUID>",
    "token": "<encoded token>",
    "updated_at": "<ISO-8601 timestamp>"
  }
}

Extract the "token" value from within the returned "auth-user" record in the response and use it as the Authorization header value in all subsequent API requests per the instructions for making authenticated API requests.

If the email address provided is not registered then a response of { "login-status": "no-user-email-fail" } will be returned.

If the provided password does not match the account, a response of { "login-status": "no-password-email-sent" } will be returned and a login email will be sent.

Delegated Authentication

Delegated Authentication is intended for use by external API clients that need to authenticate and make API requests on behalf of users.

Path	`/api/delegated-login`
Method	`POST`
Response Type	`application/json`

In order to use delegated authentication, you will need to be provided (by Yapster) a delegated authorization ID and secret with which you can construct signed JWTs (conforming to IETF RFC 7519) requesting authorization on behalf of individual users.

Constructing JWTs for Delegated Authentication Requests

Per RFC 7519 the JWT submitted to Yapster for delegated authentication should constitute the following claims:

Claim Name	Value
`iss`	the delegation authorization ID provided by Yapster
`aud`	the Yapster Org ID in which to authenticate
`sub`	the external ID of the user for whom you with to authenticate
`iat`	per the RFC—the "issued at" timestamp of the JWT

(All other standard JWT fields are optional.)

As stated above, in addition to the value of the iss claim you will also be provided with a shared secret that must be used to sign the JWT before submission.

Request Parameters

The request must include a JSON encoded request body containing:

Name	Value
token	a Base 64 encoded signed JWT as detailed above

Example Request

$ curl \
  -X POST \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"token": "<delegation token>"}' \
  'https://devapi.yapsterchat.com/api/delegated-login'

Response

A successful response will be a JSON document consisting of:

{
 "token": "<encoded auth token for user>" 
 "org_id": "<UUID of org user belongs to>", 
 "user_id": "<user UUID>",
 // … other user details 
}

Extract the "token" value from the response and use it as the Authorization header value in all subsequent API requests per the instructions for making authenticated API requests.

Retrieving Your Authenticated User Details

Forgotten who you are? Or otherwise misplaced your user ID? This is the endpoint for you.

Path	`/api/retrieve-user`
Method	`GET`
Response Type	`application/json`

Note: this endpoint has no required parameters but does require an authentication header.

Example Request

$ curl \
 -X GET \
 -H 'Accept: application/json' \
 -H "Authorization: Token <auth token value>" \
 'https://devapi.yapsterchat.com/api/retrieve-user'

Response

A successful response will be a JSON document consisting of:

{
 "id": "<user UUID>",
 "updated_at": "<ISO-8601 timestamp",
 "has-device-token": <boolean>,
 "token": "<auth token value>"
}