Securing a connection to your clinic software

• Check in your API documentation which method it uses (API key, bearer token, basic authentication or OAuth2) and the exact names it expects.
• Create credentials for AlloMia only, with only the access the agent needs. You can then turn them off without affecting your other systems.
• Anyone who can open the tool in your clinic’s dashboard can display these values with the eye icon. Give dashboard access only to people who should see them.

1. In the menu on the left, click Tools & Actions, then Tools, and click the tool.
2. Click the Authentication tab.
3. Under Authentication Type, choose one of the options below and fill in its fields.
4. Click Save Settings.

Changing Authentication Type clears what you typed for the previous type.

• No Authentication: for an endpoint that needs no credentials.
• API Key: choose the API Key Location (Header or Query Parameter), type the Key Name your API expects (for example X-API-Key or api_key), then the API Key. AlloMia sends the value exactly as typed, so include any prefix your API needs.
• Bearer Token: paste the token. AlloMia sends Authorization: Bearer YOUR_TOKEN.
• Basic Auth: type the Username and Password. AlloMia sends them base64-encoded in an Authorization: Basic header.
• OAuth2: see the next section.

1. Under Authentication Type, choose OAuth2.
2. Fill in Token URL, Client ID and Client Secret.
3. Choose the Grant Type. Server-to-server connections usually use Client Credentials. Authorization Code and Client User (Custom) also need the code from your software, in the Authorization Code field.
4. If your API asks for scopes, type them in Scope (Optional), separated by spaces.
5. Click Save Settings.
6. Under OAuth2 Token, click Get Token. The badge changes to Valid and shows the time left. If it fails, the panel shows the answer from your token endpoint.

• To get a token, AlloMia sends a POST to the Token URL with a form-encoded body: client_id, client_secret, grant_type and, if filled in, scope. With Authorization Code it adds code; with Client User (Custom), authcode.
• Your token endpoint must answer with JSON that contains access_token and, ideally, expires_in in seconds.
• Each request to your API then carries an Authorization: Bearer header with the token.
• During calls, AlloMia gets its own token and reuses it until about 5 minutes before it expires (one hour if expires_in is missing). It doesn’t use refresh tokens.
• The OAuth2 Token panel is used by the Testing tab only. Refresh gets a new token only when less than 5 minutes are left. To force a new one, for example after you change the Client Secret, click the Clear tokens icon, then Get Token. The copy icon copies the token, so you can try it elsewhere.
• An authorization code is often valid only once. With Authorization Code, check with your software company that the code stays valid. Get Token doesn’t send the code for this grant type, so it can fail even when calls work.

Further down the same tab, under HTTP Headers:

1. Click Add header.
2. Under Key, choose Content-Type, Accept or Cache-Control and pick a value, or choose Custom Header and type the header’s name and value.
3. Click Save Settings.

A custom header’s value can include a variable, for example {{patientId}}. Every header needs a key and a value, or the tool won’t save. If you chose an Authentication Type, don’t add an Authorization header here: AlloMia sets it.

On the Testing tab, click Test Tool. A 401 or 403 status means your API refused the credentials. See Testing a connection.

Known issue: with Bearer Token and Basic Auth, Test Tool doesn’t send the Authorization header the way calls do, so the test can fail even when calls work. To test before you go live, use API Key instead: API Key Location Header, Key Name Authorization, and as the API Key, the word Bearer, a space and your token (or Basic, a space and the base64 of username:password). The test and calls then send the same header.

• To change a key, token or password, open the tool’s Authentication tab, replace the value and click Save Settings. Calls that start after that use the new value.
• If credentials may have leaked, or someone who knew them leaves, change them in your software first, then here.
• Deleting a tool doesn’t turn its credentials off in your software. Do that in your software.

• 401 or 403: check the Key Name, the value, extra spaces and any prefix. For OAuth2, click the Clear tokens icon, then Get Token.
• Get Token shows an error: check the Token URL, Client ID, Client Secret and Grant Type, click Save Settings, then try again.
• The test result shows no status code: AlloMia couldn’t get an OAuth2 token, or couldn’t reach your URL. For OAuth2, click Get Token to see the error.
• “Please fill in all mandatory fields” appears when you save: fill in every field of the chosen Authentication Type, and give every header a key and a value.