> ## Documentation Index
> Fetch the complete documentation index at: https://kb.hosting.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Signing in to the API

> How a script or a terminal signs in to the hosting.com API, how access and refresh tokens work, and how to manage and revoke sessions.

This article covers signing in from a script or a terminal. If you are connecting an AI assistant such as Claude or ChatGPT, you want [Connecting AI assistants](/docs/connecting-ai-assistants-to-your-hosting-account) instead, which uses a different and simpler route.

## Which method you need

| You are                                       | Method                                                       |
| --------------------------------------------- | ------------------------------------------------------------ |
| A script, a terminal, or anything you control | **A token pair**, from your email address and password       |
| Claude, ChatGPT, or another MCP client        | **OAuth**, handled by the assistant. You never touch a token |

## Getting a token pair

Sign in at `POST /v1/auth/login` with the email address and password you use for the Hosting Panel.

You get back two tokens:

* An **access token**, which you send as a bearer token on every request and which expires fairly quickly
* A **refresh token**, which you keep, and which gets you a new pair when the access token is close to expiring

### If your account has two-factor authentication

Signing in returns a challenge rather than a token pair. Complete it at `POST /v1/auth/mfa` and you get the pair back.

A challenge allows a limited number of attempts and then expires. If you run out or leave it too long, sign in again to open a new one.

<Note>
  Sign-in is rate limited, both per email address and per account. If you are testing, space the attempts out rather than looping.
</Note>

## Keeping the session alive

Call `POST /v1/auth/refresh` with your refresh token before the access token expires, and you get a completely new pair back, including a new refresh token.

<Warning>
  **Refresh tokens are single use.** Beyond a short grace period, a refresh token works once. Presenting one a second time, or presenting one from a session that has already been closed, returns `invalid_grant` and the whole token family is treated as compromised.

  In practice this means: always store the new refresh token over the old one, and never run two processes refreshing the same session at the same time.
</Warning>

That behaviour is deliberate. If someone steals a refresh token and uses it, the moment your own process tries to refresh, the reuse is detected and the session is shut down.

## Signing out

`POST /v1/auth/logout` ends the session behind the token you send, and revokes **every token in that family** at once. Anything still holding one of them starts getting `401` immediately.

## Managing sessions

Your account keeps a list of the sessions signed in to it. You can read that list and revoke any single session without disturbing the others.

This is what you want when:

* A laptop or server with a stored token is lost, decommissioned or handed on
* A script has been retired and you want its access gone
* You are not sure what is connected and want to see the list

Revoking a session does not change your password and does not affect your other sign-ins.

## Sending requests

Send the access token as a bearer token on every call:

```
Authorization: Bearer <your access token>
```

The base address is `https://api.hosting.com`, and everything sits under `/v1`.

Reads are `GET`. Every change is a `POST` with a JSON body, including deletions, which additionally require you to repeat the thing being deleted in a confirmation field such as `confirm_domain` or `confirm_address`.

## Authentication errors

| Code            | What it means                                                    | What to do                                          |
| --------------- | ---------------------------------------------------------------- | --------------------------------------------------- |
| **401**         | The bearer token is missing, expired or revoked                  | Refresh it. If refreshing also fails, sign in again |
| **403**         | Your token is valid but lacks the scope or consent for this call | Check what the connection was granted               |
| **429**         | Rate limited                                                     | Wait for the period in the `Retry-After` header     |
| `invalid_grant` | A refresh token was reused, or came from a closed session        | Sign in again. The session is gone                  |

## Keeping credentials safe

* **Never put a token in a URL, a log line, or a public repository.** Treat the refresh token like a password, because for the life of the session it is one
* **Use a separate session per machine or script.** Sharing one refresh token between two processes will trigger the reuse protection and lock both out
* **Revoke sessions you no longer need** rather than leaving them open indefinitely

<Warning>
  hosting.com support will never ask you for an API token, a refresh token or your account password. If someone does, it is not us.
</Warning>

## Related articles

* [The hosting.com API and MCP server](/docs/hosting-api-and-mcp)
* [Connecting AI assistants to your account](/docs/connecting-ai-assistants-to-your-hosting-account)
* [Recovering account access](/docs/recovering-account-access)