Although the WebTMA Platform API uses Swagger, a certain amount of setup is needed in both the WebTMA application as well as Swagger.
Authorization with API Role
To access the Platform API, users must be authorized with the Platform API role.
When logged in to the WebTMA application:
- Go to Admin > User Management > Records and open the desired User record.
- Choose the API Roles Tab.
- Select Edit on the toolbar.
- Select the Add Role link.
- Mark the desired roles on the API Role Selection flyout.
- Choose the Add Selected button.
- Select Save on the WebTMA toolbar.
Authentication with Bearer Token
Most endpoints in the Platform API require authentication. The Platform API uses bearer token authentication.
Obtain a Token
There are many methods of interacting with an API. Two common API tools that facilitate this interaction are:
- curl (https://curl.se), a command line tool (free)
- Postman (https://www.postman.com), a browser or native app (paid with a free tier)
Using your API tool, obtain a bearer token by making a POST request to `DOMAIN/v2/Users/Authenticate` (as further specified in the Swagger documentation).
NOTE: If your username contains a backslash (e.g. `[YOUR_DOMAIN] \john.smith`), JSON requires that you escape the backslash using a double backslash. For example, `[YOUR_DOMAIN]/john.smith` will become '[YOUR_DOMAIN]//john.smith`.
A successful request will return a response body with a `Token` key/value pair.
Authorize Requests
o use a token to authenticate requests, include a header in your request like:
`Authorization: Bearer [YOUR_TOKEN]`
Your API tool should have convenient methods for providing this token on requests.
NOTE: Tokens expire after a period of hours or days. If you receive a `401 Unauthorized` response, please obtain a new token.