API Authentication

Authenticating with our API

Identity Access Management (IAM)

All external HTTP requests are authenticated against our internal IAM provider.  Consequently, all users of our API will require that an account be created within our IAM provider, and you will use this account’s credentials to access our External Orders REST API.

Please contact your Ui.Marketing representative to create your account.

Auth Token

Once your account has been created, we will provide you with your username and an auth token.

REST API

Authentication

As mentioned in our Identity Access Management (IAM) section, all HTTP requests are authenticated against our internal AIM provider by validating every HTTP request against your account’s credentials. The credentials must be included in the ‘Authorization’ header of your request as defined by the ‘basic’ authorization specification RFC 7617: RFC 7617 - The 'Basic' HTTP Authentication Scheme .

First, Get your authorization

1. An authorization consists of a grouping of advertisers. An advertiser may be associated with many authorizationsGET /authorization with your authenticationId will return all authorizations associated with your api key.

You can use any of the authorizationId returned in the above response to search for proposals and orders that are associated with the advertisers underneath that authorization. Many of our api integrators choose to simply interact with their “top level” authorization (this authorization contains all advertisers they could possibly have access to) when querying our APIs for proposals and orders
Querying for order:

1. GET /orders?authorizationId (story to add in updateSince as a query param is currently in progress) will return an object like such:

{
  "pageNumber": 0,
  "pageSize": 0,
  "totalPages": 0,
  "totalCount": 0,
  "results": [
    {
      "id": 559345,
      "status": "SOLD",
      "advertiserId": "43920",
      "ownerEmail": "example@ui.marketing.com",
      "name": "Example Name",
      "orderDetails": [
        {
          "id": 559345,
          "status": "SOLD",
          "name": "Example Name",
          "budget": 25000.55,
          "productKey": "some_1a6yr_key",
          "startDate": "2021-03-30T06:00:00Z",
          "endDate": "2021-05-30T12:00:00Z"
        }
      ]
    }
  ]
}

You can associate the advertiserId to a set of authorizations which will allow you to determine which business entities the order is associated with.

Response Codes

• 200 - When the request was successful and there is a body to be returned

• 204 - When the request was successful but there is no body to be returned 

• 401 - The user is unauthorized to call the API

• 403 - The user is authorized to call the API but does not have access to this resource.

• 404 - The requested resource was not found.

  • This should not be used for operations where multiple results are expected such as a list or search. In this case, an empty array or excluding the result from the array is the desired behavior.

• 429 - rate limit exceeded.

• 500 - An unexpected error occurred.