Using the API portal
Signing in, browsing endpoints and the try-it client - the portal for API consumers.
The API portal is a web application where you sign in with your API credentials and see the APIs those credentials can invoke. It shows live documentation - endpoints, request and response schemas, examples - together with a try-it client that invokes the real APIs. The documentation is generated from the services actually deployed on the platform, so what you read always matches what runs.
You need two things to use it, both issued by the administrators of your environment:
- The portal's address
- Credentials
Sign in
Opening the portal's address in a browser displays the sign-in page. Choose the auth type that matches the credentials you received and fill in its fields:
| Credential type | Auth. type | Fields |
|---|---|---|
| Username and password (Basic Auth) | Basic Auth | Your username and password |
| Bearer token | Bearer token | The token itself, either a static token or a JWT |
| Bearer token | Basic Auth | Your client ID as the username and your client secret as the password |
| API key | API Key | The key itself |
A token is verified the same way a REST channel verifies it, and a JWT is accepted only for as long as it is valid - once it expires, the portal returns to the sign-in page.
A session lasts eight hours. It ends earlier when your credentials are changed or deactivated, and the portal then returns to the sign-in page.
The Show button next to a password, a key or a token displays what you typed. With wrong credentials, the sign-in page shows only an error message - no API details are visible before a successful sign-in.
What you see and why
The document you receive after signing in contains only the endpoints your credentials can invoke. The filtering takes place on the platform's servers before anything reaches your browser, and other callers' endpoints are never sent to you.
If an endpoint you expect is missing from your view, your credentials do not grant it - ask your admins to check what your account has been assigned.
Try endpoints out
The navigation on the left lists the endpoints in groups, named after their URL paths. The endpoints of a small API form a single group, e.g. Billing for everything under /api/billing, and a larger API is a section of its own, divided into groups by the resource that follows it, e.g. Patients under Healthcare for everything under /api/healthcare/patients. Each group shows how many endpoints it has, and only the selected group is expanded. The filter above the navigation narrows it down by URL path, HTTP method or description, and expands every group with matches while it is in use. The navigation can be resized by dragging its right edge and collapsed with the button next to the filter, and the portal remembers both in your browser.
Selecting a group shows the list of its endpoints, each with its HTTP method and its full URL path, and next to the list the endpoint selected in it, with its description, a sample request and the response. The filter above the list narrows it down the same way the navigation's filter does, Enter shows the first endpoint still listed and Escape empties the filter. The list and the endpoint scroll separately, and selecting an endpoint in the navigation selects it in the list too. The handle between the list and the endpoint resizes the list, and the portal remembers its width in your browser and applies it to every group.
The address in your browser always names the endpoint shown, e.g. /#post/api/healthcare/referrals, so a link copied from it opens the portal at the same endpoint. A link opened before signing in is followed once you have signed in.
The sample request is a JSON object with values chosen from the names of the fields. It holds the query string parameters and the body fields of the endpoint, and the portal places each value where it belongs when the request is sent. Path parameters, e.g. {referral_id} in /api/healthcare/referrals/{referral_id}, have inputs of their own in the path shown above the request. The request can also be written as key=value lines, the same as in the Dashboard - one field per line or separated with semicolons, lines starting with # are skipped, and numbers, True, False and None are sent as such. Any other request, e.g. XML or base64, is sent exactly as typed, as application/xml when it is XML and as text/plain otherwise, unless you set a content type of your own under Options. Edit the request if needed and press the play button, or Ctrl+Enter anywhere in the request. The portal sends a real request to the actual API, using the credentials you signed in with - the same permissions apply as when you call the endpoint directly from your own code - and shows the response below the request, with its status code, the time it took and its body.
Each endpoint has these tools next to its URL path, its request and its response:
| Tool | What it does |
|---|---|
| Spec | Opens a window with the endpoint's input and output fields, their types and which of them are required. The window stays open while you edit the request, it shows whichever endpoint is selected, and it can be moved by its title bar and resized by its corner. Copy as in the window copies the fields as text or as JSON |
| Link | Copies the link to the endpoint |
| Example | Replaces the request with an example that has every field of the endpoint, including the optional ones the sample request leaves out |
| Pretty print | Indents a JSON request and aligns the values of key=value lines - a request that is neither is left as it is and the editor is outlined to show it |
| Options | Adds your own HTTP headers to the request, e.g. a correlation ID |
| History | Lists the earlier invocations of the endpoint - selecting one brings back its request, its headers and its response |
| Raw | Shows the request as it is sent and the response as the endpoint returns it, with the request line or the status line, the headers and the body |
| Copy | Copies the request or the response, in its raw form when Raw is on |
The history is kept in your browser tab only and is cleared each time the sign-in page appears, whether you sign out or your session ends.
Connect your own tools
The document behind the portal is a standard OpenAPI 3.1 specification, available in two formats under the portal's address:
Paste either URL into Postman, an API gateway, a code generator or any other tool that supports OpenAPI, and authenticate with the same credentials you sign in with. The document is always current - it is regenerated whenever the services behind it change, so there is no stale export to refresh.
Call the APIs from your code
The URL, HTTP method and schemas shown for each endpoint are the live contract of that API. A minimal call with curl, using Basic Auth credentials:
For anything larger, generate a client from the spec URL above - the generated code stays correct for as long as the contract shown in the portal does not change, and the platform's administrators are notified of contract changes whenever the APIs are redeployed.
Sign out
Use the Sign out link in the portal. Your session ends and the sign-in page appears again - the spec URLs also stop responding for your session until you sign in once more.
For administrators
If you run the platform yourself, the OpenAPI administration page covers the portal's architecture, which channels are documented, branding and ports.
See also
| Page | What it covers |
|---|---|
| OpenAPI specifications | Downloadable specification files and the HTTP endpoint |
| Authentication | The credentials that sign you in to the portal |
| API versioning | The deprecation badges and sunset dates the portal shows |