← All guides

How to give an API key to a contractor

Updated

A contractor needs access to an API your product uses: a payment provider, a cloud account, a mapping service. The fastest thing is to copy the key from your settings page and send it over. The better thing takes about ten minutes longer, and most of that time is spent before the key is sent at all.

First: should it be your key?

Usually not. Almost every serious API lets you create more than one key, and a key made for this contractor is better than yours in every way that matters:

  • You can revoke it without breaking anything. When the contract ends, or the key leaks, you switch off theirs. With a shared key, turning it off takes production down with it, so in practice nobody does.
  • You can tell who did what. Requests made with their key show up under its name in the provider's logs.
  • It can do less. Most providers let a key be limited: read-only, test mode only, one project, one bucket, a list of allowed IP addresses. Give the contractor what the work needs and nothing else.
  • It can expire. If the provider supports an expiry date, set it to the end of the contract. A key that switches itself off cannot be forgotten.

If the provider really only offers one key per account, consider giving the contractor access to a separate test account, or doing the parts that need the live key yourself.

Where not to send it

An API key is a password that does not ask for a second factor. Anyone who has it can use it, from anywhere, and nothing tells you it has been copied. So keep it out of the places that keep things:

  • Email, which stays in two mailboxes and their backups indefinitely.
  • Tickets and project boards, which everyone on the project can read, including people added later.
  • Chat messages, which are searchable and synced to every device.
  • The repository. Not in a config file, not "just for now", not in a private repo. Keys committed to git stay in its history after the line is deleted, and automated scanners look for exactly this.

How to hand it over

Send the key through a link that is encrypted in your browser and can be opened once. With PassAlong:

  1. Paste the key. In the same box, add a line saying what it is for and which environment it belongs to, so it does not get used against production by mistake. Most keys and connection strings fit easily: the limit is 3,000 characters.
  2. Pick a lifetime that matches when the contractor will actually open it. If they are in another time zone, a day is more realistic than an hour.
  3. Keep "Destroy after it is opened" on, create the link, and send it by whatever channel you normally use.
  4. Keep your own link. It tells you when the key was opened, so you do not have to ask whether it arrived.

The key is encrypted before it leaves your browser, and the decryption key stays in the part of the link after the #, which never reaches our server. The details, and what the server does store, are in How it works.

Confirm it went to the right person

When the contractor says they have the key, check your own link. If it shows the key was opened before they got to it, or they tell you the link had already been used, assume someone else has it: revoke the key at the provider and send a new one. This is the other reason to give the contractor their own key. Replacing it is a routine operation, not an incident.

Ask where it will live

The handover is only half of it. Before you send the key, agree where the contractor will keep it: in a secret manager, or in environment variables on their machine and CI, never in the code. If the project has a .env file, check that it is in .gitignore before the first commit, not after.

If the contractor needs to send you something back, such as a key for their own staging server or a database password, they can use the same kind of link: on the page where they open your secret there is a button to reply with one of their own.

When the work is done

  1. Revoke the contractor's key at the provider. With a separate key this takes a minute and breaks nothing.
  2. If you did share your own key after all, rotate it: create a new one, deploy it, then revoke the old one. A new password or passphrase for anything else they had access to comes from the password generator.
  3. Check the provider's logs for requests made with the old key after the date it should have stopped.