# Authentication

Every request except two keyless ones sends an API key, `sfs_` followed by **32** letters and digits, as `Authorization: Bearer sfs_…`.

## Get a key

Sign in at [installgraph.com/login](https://installgraph.com/login) (an emailed link, no password). Your key is on your [dashboard](https://installgraph.com/account). New accounts are made in the browser only: at most 3 per IP per day, and disposable addresses are refused. Free credits need a company email: 25 at sign-up and 25 more once the link is clicked (once per company domain); webmail gets none.

A key is shown once. Every key on an account shares the account's credit balance. Lost it? Regenerate it on the dashboard: that revokes the old one.

## Send it

```bash
curl "https://api.installgraph.com/v1/usage" -H "Authorization: Bearer $INSTALLGRAPH_API_KEY"
```

`X-API-Key: sfs_…` works too.

In a browser, add the key to the URL instead: `https://api.installgraph.com/v1/usage?key=sfs_…`. A header wins if both are sent.

## Keep it secret

- A key in a URL (`?key=`) is fine for your own browser, but it stays in your browser history: don't share those links.
- Never put the key in a web page or app you publish: anyone can read it there and spend your credits. From code, use the header.
- Keep it in an environment variable or secret store, not in source control. The `sfs_` prefix lets secret scanners spot a leaked key.
- If a key leaks, revoke it on your account page and make a new one. Revocation takes effect on the next request.

## Scopes

| Scope | Endpoints |
| --- | --- |
| `companies:read` | [`GET /v1/companies/{domain}`](https://installgraph.com/docs/reference/get-company.md), [`GET /v1/apps/{slug}/companies`](https://installgraph.com/docs/reference/list-app-companies.md), [`GET /v1/apps/{slug}/companies/count`](https://installgraph.com/docs/reference/count-app-companies.md) |
| `apps:read` | [`GET /v1/apps`](https://installgraph.com/docs/reference/list-apps.md) |
| `events:read` | [`GET /v1/events`](https://installgraph.com/docs/reference/list-events.md) |
| none | [`GET /v1/usage`](https://installgraph.com/docs/reference/get-usage.md), [`GET /v1/industries`](https://installgraph.com/docs/reference/list-industries.md), [`POST /v1/billing/purchase`](https://installgraph.com/docs/reference/agent-purchase.md) |

Keys made at sign-up have all three scopes. [`GET /v1/usage`](https://installgraph.com/docs/reference/get-usage.md) shows a key's scopes.

## No key needed

[`GET /v1/pricing`](https://installgraph.com/docs/reference/get-pricing.md) and [`GET /v1/public/stats`](https://installgraph.com/docs/reference/get-public-stats.md) take no key.

## Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `missing_api_key` | No key was sent. |
| 401 | `invalid_api_key` | The key is not one we issued. |
| 401 | `api_key_revoked` | The key was revoked. |
| 403 | `insufficient_scope` | The key lacks this endpoint's scope. |
| 403 | `api_key_suspended` | The key is suspended. |