The situation
A setup screen asks for a key so one service can reach another. You paste it in, the connection works, and months later you no longer remember what the key permits, where it is stored or what stops an accidental request from changing real data.
The idea in one paragraph
A service connection is permission crossing a boundary. An API defines the requests another program may make, while a credential identifies the caller and grants some amount of access. Connecting two systems therefore creates a path for both useful work and mistakes. Give the narrowest permission that completes the job, and keep the credential outside code and published files.
One connection, four questions
| Part | Ask | Safer default |
|---|---|---|
| Identity | Who is calling? | A separate credential for this job |
| Permission | What may it do? | Only the required actions |
| Storage | Where is the secret kept? | A protected environment setting |
| Failure | What happens twice? | A repeat-safe operation |
How it actually works
One service sends a request to an address exposed by another. The receiving service checks the credential, applies its permission rules and returns a result. Some connections are immediate; others deliver events later. Either can fail halfway through or be retried, so the same request may arrive more than once.
What this changes for you
- Record every connection, its purpose, owner and permission level.
- Use separate credentials for development and production.
- Design writes so a retry does not create a second payment, message or record.
Where it breaks
Narrow credentials reduce damage but do not make incorrect requests correct. A leaked key still needs rotation, delayed events still need monitoring, and two services can disagree about whether a request succeeded. Treat the boundary as an operating responsibility, not finished setup.
Terms used on this page
- API: a defined way for one program to request work from another.
- Credential: a secret or identity used to prove who is calling.
- Repeat-safe: producing one intended result even when the same request arrives again.
Read next
Errors and logs shows how to inspect the evidence when a connection or program fails.