Managing your API access

This page is for the person inside your organisation who owns the Scratch Power integration. The good news: most of what you'll do here is point-and-click in the Scratch Power web portal (your normal admin dashboard).

The page is laid out in two layers. Each task has a portal walkthrough first — that's for everyone, no code needed. Then an "Or via the API" subsection — that's only for engineers who want to script the same thing from their own systems. If you're non-technical you can ignore the API subsections entirely; the portal does everything they do.

A quick recap: what you have to keep safe

When you signed up to integrate, Scratch Power emailed you four pieces of information. Together they let your software prove who it is when it talks to Scratch Power. They come in two pairs — one pair identifies the application, the other identifies the user that application runs as.

Pair 1 — identifies the application

Pair 2 — identifies the user inside Scratch Power

You also got your organisation code (e.g. ACME) and, for the staging environment, a list of test meter numbers — see Testing for that side of things.

The two things that go wrong

There are really only two problems that bring people to this page:

1. "I've lost my client secret" or "My client secret has leaked" → you need to rotate the secret. See How to rotate your client secret below. This is the recommended path — almost always the right answer.
2. "My integration user has forgotten their password" → you send a password reset link to them. See How to reset your integration user's password.

There's also a third, less common option — creating a brand-new API client from scratch. Most people don't need this; you'd only do it when you're adding a second, separate integration (e.g. a new mobile app on top of your existing system). Rotation is better than re-creation when you're trying to recover an existing integration. See Creating a new API client.

Before you start: do you have the right permissions?

The screens you'll use live inside the Administration section of the portal. Whether you can see them depends on the permissions your user has been granted.

The simplest test: sign in and look at the left-hand menu. If you can see Administration → Auth Clients and Administration → Actors, you have what you need. Skip to the next section.

If those menu items are missing, you need one of the permissions in the table below. Ask an admin in your organisation to grant the relevant one, or to do the steps for you.

(For engineers checking permissions in code: these correspond to ROLE_MANAGE_AUTH_CLIENTS, ROLE_MANAGE_ACTORS, and ROLE_RESET_USER_CREDENTIALS respectively. Either of the last two satisfies the password-reset flow.)

Permissions are granted via Administration → Profiles. If your org has a "Profiles" admin, that's who to ask. The in-portal help page is at Help → Administration → Profiles.

How to rotate your client secret (recommended)

Rotating means generating a brand-new client secret and throwing away the old one. The new secret is shown once on screen, you copy it, you (or your engineer) put it into the software's configuration, and the software starts using it. After that, the old secret stops working — instantly — and every request to the API has to use the new one.

Rotate when:

• You've lost your current secret and need a working one.
• You suspect the secret has leaked (someone emailed it, pasted it in Slack, committed it to git, etc.).
• It's been a long time and you're cleaning up as part of a routine security check.
• An engineer who had production access has left the company.

Step by step:

1. Sign in to the portal at app.scratchpower.com (or app.staging.scratchpower.com if you're working in the test environment).
2. In the left-hand menu, open Administration → Auth Clients.
   The page will show one card per integration. Each card has a Client ID at the top (like acme-mobile-app).
3. Find the card for the integration whose secret you want to rotate. Click anywhere on the card — a panel slides in from the right with the client's details.
4. Scroll to the bottom of that panel. You'll see a red Rotate Secret button.
5. Click Rotate Secret. A confirmation dialog appears: "Rotate Client Secret? This will invalidate the current secret. Any applications using this client will need to be updated with the new secret." Click Confirm.
6. The new secret is displayed inline, masked behind dots. Click the eye icon to reveal it, then click Copy Secret. The secret is now in your clipboard.
7. Hand the new secret to whoever maintains your software so they can update its stored credentials. If that's you and you know how, paste it where the old secret was stored — that's usually environment variables on your servers, or a secrets manager like AWS Secrets Manager, 1Password, or Vault. The secret is shown once on screen and never again — don't navigate away until it's saved somewhere durable.
8. The engineer then restarts or redeploys the software so it picks up the new secret. Until they do, every request the software sends will fail because it's still trying the old (now-dead) secret.

Or via the API

Endpoint: PATCH /clients/{client_id}/reset
Auth: Bearer access token, caller must have Manage Auth Clients (ROLE_MANAGE_AUTH_CLIENTS).
Request body: none.
Path parameters:

Example:

curl -X PATCH https://api.scratchpower.com/clients/acme-mobile-app/reset \
  -H "Authorization: Bearer $TOKEN"

{
  "secret": "59ceadf8-bn4b-46e2-93b2-3efafedcab1c"
}

Response fields (200 OK):

Errors:

If you'd like to see screenshots and the full reference for this screen, the in-portal help page is at Help → Administration → Auth clients.

How to reset your integration user's password

The integration user is the person-shaped account inside Scratch Power that your software logs in as. If that account's password has been lost or you want to rotate it, you don't type a new password yourself — you send a password reset link to the user's registered phone number and email. They click the link, set a new password (and a PIN — a short numeric code used by the portal for a few sensitive operations), and you put that new password into your software.

Step by step:

1. Sign in to the portal at app.scratchpower.com (or app.staging.scratchpower.com).
2. In the left-hand menu, open Administration → Actors.
   (An "actor" is what we call any user or system account inside your organisation — the term covers both humans and the integration user your software logs in as.)
3. Find the row for your integration user (usually named something like acme-integration or dealer). Click the row to open the edit panel.
4. Scroll to the Account actions section near the bottom.
5. Click Send Password Reset Link.
6. Confirm the action. A toast at the top right reads "Password reset link sent via SMS and email".
7. The integration user receives both an SMS and an email with a one-time setup link. They click it, choose a new password and PIN, and that's it.
8. Once they've set the new password, hand it to your engineer (or update it yourself if you maintain the software) so the software's stored password is refreshed. Then a restart / redeploy picks up the change.

Or via the API

Endpoint: POST /api/admin/users/{id}/send-reset-link
Auth: Bearer access token, caller must have Manage Actors (ROLE_MANAGE_ACTORS) or Reset User Credentials (ROLE_RESET_USER_CREDENTIALS). Platform admins can issue resets cross-org; org-scoped admins are restricted to actors in their own organisation.
Request body: none.
Path parameters:

Alternate path: POST /api/admin/users/{id}/reset-password — same handler, same behaviour, kept for backwards compatibility with the legacy URL.

Example:

curl -X POST https://api.scratchpower.com/api/admin/users/6/send-reset-link \
  -H "Authorization: Bearer $TOKEN"

{
  "success": true,
  "message": "Password reset link sent to the user's email and phone."
}

Response fields (200 OK):

Errors:

A 200 confirms the token was issued and the dispatch calls were made. Delivery is asynchronous — the SMS and email leave the queue shortly after the response returns. If neither arrives within a couple of minutes, check the actor's phone_number and email fields under Administration → Actors before reissuing.

If you'd like more detail on managing users in general, the in-portal help page is at Help → Administration → Actors.

Creating a new API client (only when you need a second integration)

This section is for the rare case where you genuinely need a second, separate set of API credentials — for example, you're about to launch a mobile app alongside your existing point-of-sale software, and you want them to have independent client IDs so they can be revoked separately. If you're trying to recover lost credentials, don't do this — rotate the existing secret instead. Rotation keeps your historical audit trail clean and avoids duplicate-client clutter.

Step by step:

1. Sign in to the portal at app.scratchpower.com.
2. In the left-hand menu, open Administration → Auth Clients.
3. Click the + New Client button (top right of the page).
4. Fill in the dialog:
   • Client ID — a short, human-readable name with no spaces. Only letters, numbers, hyphens and underscores. Example: acme-mobile-app. This name is public; pick something descriptive so you'll recognise it later.
   • Description (optional) — a one-liner explaining what this client is for. Example: "Mobile app API access — iOS & Android". You can change this later from the detail panel.
   • Scopes — tick read if the integration needs to read data and write if it needs to make purchases.
   • Grant Types — tick the boxes that match how your software signs in. For most integrations you want Password and Refresh Token ticked, the others left unticked. If your engineers told you specific values, follow their lead.
   • Access Token TTL (seconds) — how long an issued access token stays valid before your software has to refresh it. Default 3600 (= 60 minutes). Leave alone unless you have a specific reason. (TTL stands for "time-to-live" — the time the token works for.)
   • Refresh Token TTL (seconds) — how long a refresh token stays valid. Default 7776000 (= 90 days). Leave alone unless you have a specific reason.
5. Click Create Client. The new secret is shown once, masked behind dots — click the eye icon to reveal it, then Copy Secret.
6. Hand the secret (and the new Client ID) to your engineer so they can put it into the new integration's configuration. If you're the engineer: paste it into the new app's environment variables / secrets manager, deploy, and confirm it can log in.

Or via the API

Endpoint: POST /clients
Auth: Bearer access token, caller must have Manage Auth Clients (ROLE_MANAGE_AUTH_CLIENTS).
Content-Type: application/json

Request body fields:

Example:

curl -X POST https://api.scratchpower.com/clients \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "acme-mobile-app",
    "description": "Mobile app API access — iOS & Android",
    "scope": ["read", "write"],
    "grant_types": ["password", "refresh_token"],
    "access_token_validity": 3600,
    "refresh_token_validity": 7776000
  }'

{
  "client": {
    "id": 17,
    "client_id": "acme-mobile-app",
    "scope": ["read", "write"],
    "grant_types": ["password", "refresh_token"],
    "access_token_validity": 3600,
    "refresh_token_validity": 7776000,
    "description": "Mobile app API access — iOS & Android"
  },
  "secret": "1c7f4b2a-5d9e-4cf2-8a3b-72e9a1d4b6c0"
}

Response fields (200 OK):

GET /clients/{client_id} returns the same client object without the secret field, since the platform stores only a one-way hash of the secret. The secret is irretrievable after this response — your only recovery path is rotation (PATCH /clients/{client_id}/reset).

Errors:

The in-portal help page at Help → Administration → Auth clients covers the create form in more detail, including a field-by-field reference.

Got completely locked out?

If you've lost the credentials and you also can't sign in to the portal yourself, you'll need a human to help. Email support@scratch-power.com from the address registered to your organisation and explain what you need restored. We'll verify identity out-of-band before issuing fresh credentials. Always include:

• Your organisation code (e.g. ACME).
• Your Client ID (the public one — it's safe to include).
• A description of what you've already tried.

Quick reference

Every API endpoint above requires a Bearer access token (see Authentication) and a user with the relevant permission — Manage Auth Clients for the /clients endpoints, Manage Actors or Reset User Credentials for the reset-link endpoint.