Live environment

Referrals made with these keys reach real services, and are sent to the patient's GP practice. Try changes on the test site first.

Frontline API

The API reads the library of local services and makes referrals into them. Everything below works against https://southend-on-sea.essexfrontline.org.uk.

Authentication uses two tokens. Sign in with your Frontline account and both are shown on screen.

Get my keys

1Access and refresh tokens

Access token

Sent with every API call, as Authorization: Bearer ...

Expires after 180 minutes. Calls made with an expired token return 401.

Refresh token

Stored by your system, and exchanged for a new access token when one expires. It changes only when you regenerate it.

Treat it like a password.

Keep it on a server, never in a browser, a URL, or a source repository.

2Getting your keys

Sign in with your Frontline account and your keys are shown on screen, ready to copy. API access has to be switched on for your account first. If the page says it is not enabled, ask your Frontline contact to turn it on.

Open /apikeys

Sign in with your Frontline account

                Copy both tokens
                shown on the page
            

Get my keys

3Calling the API

Send the access token as a Bearer token on every request:

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     https://southend-on-sea.essexfrontline.org.uk/api/token/status

That endpoint reports who you are authenticated as. Use it to check a token works before writing anything else.

4Refreshing an expired token

After 180 minutes the access token stops working. Exchange your stored refresh token for a new one:

curl -X POST -H "Content-Type: application/json" \
     -d "{ \"refreshToken\": \"YOUR_REFRESH_TOKEN\" }" \
     https://southend-on-sea.essexfrontline.org.uk/api/token/refresh

The response carries a new access token and the moment it expires:

{
  "result": "OK",
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "8f3c1d2e-...",
  "valid_to": "2026-09-17T14:32:00Z"
}

                Call the API
                with the access token
            

401 returned the token has expired

POST refresh /api/token/refresh

You get a new access token, and carry on calling the API.

5Trying it without writing code

The API reference, with a "Try it out" button on every endpoint, is on the test site. Open it there.

Keys are per site. To try an endpoint on the test site, collect a set of keys there as well.

Signing your own users in

To sign Frontline users in and call the API on their behalf, send them to /apilogin?returnUrl=your-url. They are returned to you with ?token= appended.

That places a live access token in a URL, where it can reach browser history, server logs and referrer headers. Use the keys page unless each user has to authenticate as themselves, and do not log the returned URL.