Authentication

Some of the API requests (especially the ones that are read-only GET requests) do not require any authentication. The other ones, that modify data into the database, require broker authentication via API key. Additionally, owner tokens are issued to facilitate multiple actor roles upon object creation.

API keys

API key (you could also saw broker key) is username to use with Basic Authentication scheme (see RFC 2617#section-2).

You can pass your API key with Authorization HTTP request header in the following form: | “Authorization”: “Bearer <your_api_key>” (without triangular brackets)

Owner tokens

Getting token

The token is issued when object is created in the database:

POST /api/2.4/auctions HTTP/1.0
Authorization: Basic YnJva2VyOg==
Content-Length: 195
Content-Type: application/json
Host: api.atreus.auction

{
  "data": {
    "title": "casings for state awards",
    "value": {
      "amount": 500
    },
    "minimalStep": {
      "amount": 35
    },
    "items": [
      {
        "description": "casings for state awards",
        "quantity": 5
      }
    ],
    "tenderPeriod": {}
  }
}


201 Created
Content-Type: application/json
Location: http://api.atreus.auction/api/2.4/auctions/6dc0619d4e5b475498b76260e128c00a
X-Content-Type-Options: nosniff

{
  "data": {
    "status": "active.tendering",
    "title": "casings for state awards",
    "dateModified": "2019-11-11T14:39:25.236301+02:00",
    "owner": "broker",
    "items": [
      {
        "id": "bd0746ddc77a49c5a1b23b01579fa680",
        "description": "casings for state awards",
        "quantity": 5
      }
    ],
    "auctionPeriod": {
      "shouldStartAfter": "2019-11-11T14:44:25.233892+02:00"
    },
    "tenderPeriod": {
      "startDate": "2019-11-11T14:39:25.233892+02:00",
      "endDate": "2019-11-11T14:44:25.233892+02:00"
    },
    "value": {
      "amount": 500.0,
      "currency": "USD"
    },
    "minimalStep": {
      "amount": 35,
      "currency": "USD"
    },
    "procurementMethodType": "english",
    "id": "6dc0619d4e5b475498b76260e128c00a",
    "numberOfBids": 0,
    "next_check": "2019-11-11T14:44:25.233892+02:00",
    "auctionID": "broker: casings for state awards",
    "auctionUrl": "http://auction.localhost/english-auctions/6dc0619d4e5b475498b76260e128c00a"
  },
  "access": {
    "token": "4f8afe4b6c564bba8aa0721eb6aac1f0"
  }
}

You can see the access with token in response. Its value can be used to modify objects further under “Owner role”.

Using token

You can pass access token in the following ways:

  1. acc_token URL query string parameter
  2. X-Access-Token HTTP request header
  3. access.token in the body of POST/PUT/PATCH request

See the example of the action with token passed as URL query string:

GET /api/2.4/auctions/6dc0619d4e5b475498b76260e128c00a?acc_token=4f8afe4b6c564bba8aa0721eb6aac1f0 HTTP/1.0
Authorization: Basic YnJva2VyOg==
Host: api.atreus.auction


200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff

{
  "data": {
    "status": "active.tendering",
    "title": "casings for state awards",
    "dateModified": "2019-11-11T14:39:25.236301+02:00",
    "owner": "broker",
    "items": [
      {
        "id": "bd0746ddc77a49c5a1b23b01579fa680",
        "description": "casings for state awards",
        "quantity": 5
      }
    ],
    "auctionPeriod": {
      "shouldStartAfter": "2019-11-11T14:44:25.233892+02:00"
    },
    "tenderPeriod": {
      "startDate": "2019-11-11T14:39:25.233892+02:00",
      "endDate": "2019-11-11T14:44:25.233892+02:00"
    },
    "value": {
      "amount": 500.0,
      "currency": "USD"
    },
    "minimalStep": {
      "amount": 35,
      "currency": "USD"
    },
    "procurementMethodType": "english",
    "id": "6dc0619d4e5b475498b76260e128c00a",
    "numberOfBids": 0,
    "next_check": "2019-11-11T14:44:25.233892+02:00",
    "auctionID": "broker: casings for state awards",
    "auctionUrl": "http://auction.localhost/english-auctions/6dc0619d4e5b475498b76260e128c00a"
  }
}