Atlas API: Getting started
This guide will help with setting up a connection to the ATLASacc APIs, as well as explaining the main concepts of how the APIs are structured and used.
Developer Portal
API documentation is a living thing, it constantly changes. Therefore, we use tools to dynamically create our technical API documentation. You'll find all API documentation under 'API's.
The ATLAS Developer Portal can be found at the following places:
Acceptance environment: https://tba-shared-apimanagement-acc-we-api.developer.azure-api.net
Production environment: https://tba-shared-apimanagement-prod-we-api.developer.azure-api.net
To login to the Developer Portal you use your ATLAS account (see ATLAS Login). Note that the acc and prod environments are entirely separate: an acc ATLAS account does not work for the prod Developer Portal just like a prod ATLAS account does not work for the acc Developer Portal.
The documentation between acceptance and prod should not differ too greatly, but because of the nature of live documentation, there might be updates available on acceptance that have not yet been deployed to production.
Our APIs will constantly update, but we do aim to do this in a backwards compatible manner. This means that your client code should allow for unknown properties in the JSON responses, as we can always add more properties to existing endpoint responses.
Authorization & Authentication
The ATLAS APIs utilize a few layers of security. We'll explain the basic concepts in this section.
ATLAS Login
Almost all requests to the ATLAS APIs require to be made in name of an ATLAS user. This is done through a bearer token (see next subsection).
An ATLAS account can be created at:
Acceptance: acc-atlas.tbauctions.com
Production: atlas.tbauctions.com
Contact support if help is needed with this process.
This ATLAS account can be used to log into the ATLAS portal which can be of great help to see whether your API calls had the intended effect.
Note that the acc and prod environments are entirely separate: a login for acc ATLAS does not work for prod ATLAS and vice versa.
Bearer token
User authorization in ATLAS is done through a so-called bearer token or jwt.
This token needs to be included in (almost) every API call you make as a http header with name Authorization
Authorization: bearer <token goes here>The bearer token is only valid for a short amount of time, and can be retrieved for your user account in two ways:
Manually through the atlas portal. Inspect the network calls and copy your token from one of the many calls the frontend makes to the Atlas backend.
Programmatically through the login endpoint (see developer portal)
The token is a JWT token and can therefore be decoded with websites like jwt.io . This can be helpful to see your account information.
Subscription key
Currently, the ATLAS APIs do not enforce the use of a subscription key, but this will likely change in the future, and we will update you when that happens.
Company and buyer scoping
In the documentation of some endpoints you will find an optional or required query parameter called companyScopeIds and/or buyerScopeIds. These query parameters are used to scope the request down to a specific sub-view of our data.
For most API integrations the companyScopeIds will need your companyId as a value. This id can be found by decoding your jwt token as described in the Bearer token subsection.
Although the companyScopeIds parameter may be shown as optional, it can still be required for non-admin accounts. We are working on making these optional for every user by automatically filling in the value. This is not yet the case on some endpoints.
API Areas
Atlas is split up in three different logical areas, which we'll explain in this section.
Pre-auction
The pre-auction area is all about the set-up for the auction. Here we create items, attach images to those items and set-up auctions to publish to the auctioning platforms like BVA and Troostwijk.
Auction
Auctions are mostly run on "external platforms" like BVA and Troostwijk. The Atlas APIs don't directly tie into live auction data.
Post-auction
After an auction is closed, the items are sold and invoiced through Atlas. The order data can then be shared through the APIs.
Entities
In this section will briefly look at some main domain entities you can come across while using the Atlas APIs.
Pre-auction
Items
Items are the main objects that will form a lot on an auction. An item contains all the attributes that describe the item and its current state. Images can be linked to items for displaying with the auctions.
Categories
Each item belongs to a category. A category contains all information on which attributes can or should be specified for items that belong to that category. Category data changes rarely and can be cached on the client side for a long time.
Categories have a nested structure, for example: the "car" category is a sub-category of the "vehicle" category. You will always create your item under one of the sub-categories.
Companies/Sellers
Each seller has its own company on Atlas. All items and contracts will be linked to that company.
Each user in a company can see the imports and items that belong to that company. A user can belong to multiple companies. A non-admin user can only create imports and items under his/her own company.
Company-Agreements
A company-agreement is a contract specifying all the rules that items will be sold under. Each company can have multiple company-agreements.
These agreements are created by TBAuctions employees in collaboration with the seller company.
Company-agreements need to be linked to imports and items to specify under which contract those specific items will be sold.
Imports
Imports are logical batches of items. First an import is created, after which items can be created under it. An import is validated and processed as a whole. Items within an import do not necessarily end up together in one auction.
Locations
Locations are used for pick-up information. If the items are to be picked up after auction, then the correct location need to be linked to those items beforehand.
Auction
In the context of pre-auction, an auction is the set-up for the actual auction. Auctions can not be made through the APIs. All auctions are created by internal employees of TBAuctions. They will combine items in auctions and publish those auctions to specific or all auction platforms.