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

# Authentication and API Keys

> This guide will walk you through the two different credentials you need to work with Portal.

There are two different types of authentication used with Portal integration: a **Portal API Key** for server side requests and a **Client Session Token** (also shown as Client API Key) for authenticating SDK users.

The **Portal API Key** is used server side to create new Client Session Tokens, fetch information about clients, or access other endpoints in the [Custodian API](../apis/custodian/api-reference-link).

The **Client API Key** is used to initialize the Portal SDKs in order to authenticate an end user ("client"). It can also be used with the Enclave MPC API or other endpoints in the [Client API](../apis/client/api-reference-link).

<Note>
  Reach out to us on [Slack](https://join.slack.com/t/portalcommunity/shared_invite/zt-1zlyexf43-A94Z4ugntrgLGs2j5slmeQ) to get access to the Admin Dashboard and start developing!
</Note>

<Note>
  This page covers the credentials you manage yourself. Portal can also
  authenticate your end users for you, with an email magic link, Google, or Apple,
  and issue the Client Session Token as part of that sign-in. See
  [Authentication](/resources/authentication/overview).
</Note>

## Portal API Keys

This is the API key used by your server to make requests to Portal.

### Creating a Portal API Key

1. Log in to [app.portalhq.io](http://app.portalhq.io/).
2. Navigate to Settings -> Custodian API Key.
3. Press "New" to create a new Portal API Key.

<Warning>
  Before going live with real users, always ensure that you create clients using a Portal API Key from your Portal's **Production** environment. Read more [here](./going-to-production) on going live with real users.
</Warning>

## Client Session Tokens

Users (clients) are required to authenticate their devices to Portal in order to create wallets and submit transactions. **Client Session Tokens** **(CST)** are *short-lived*, *auto-refreshing* tokens used to authenticate users to Portal.

**Short-Lived**\
CSTs expire after 24 hours of no activity. After this, a new CST must be requested from your backend.

**Auto-Refreshing**\
Every authenticated request with a CST updates the token's expiry to 24 hours from that request time. There's a max refresh duration of 7 days, after which a CST can no longer be auto-refreshed.

The goal of this system is keep sessions short (reducing attack windows) while minimizing the number of requests needed to create sessions.

#### In Practice:

* **Active User**:  If a user uses Portal daily, their CST expiry extends by 24 hours each day. They'll need a new CST from your backend only once per week (after hitting the 7-day max refresh duration).
* **Inactive User**: Users logging in after a few days or weeks will need a new CST from your backend on every login since CSTs expire after 24 hours.

### Creating a Test Client API Key

If you'd like to quickly test out a Portal SDK or the [Enclave MPC API](../apis/enclave-mpc/guide/create-a-client) you can generate a Client *API Key* from the Portal Admin dashboard! It has the same permissions as a Client Session Token, except that it doesn't expire. This is helpful for development!

<Note>
  Client API Keys are associated with a single wallet! So you will need to create multiple test credentials if you want to generate more than one wallet.
</Note>

1. Log in to [app.portalhq.io](http://app.portalhq.io/).
2. Navigate to Settings -> Test Client API Keys.
3. Press "New" to create a new Client API Key.

### Creating Client Session Tokens in your Application

To authenticate mobile users with Portal, they need a unique Client Session Token. Request this token from your backend using the Portal API Key, then share it with mobile users after they log in.

#### Initial Registration

When a user first registers for your mobile app, use your Portal API Key to create a Client Session Token. Remember to associate the returned `clientId` with the user in your system.

```typescript theme={null}
const response = await axios.post(
    `https://api.portalhq.io/api/v1/custodians/clients`,
    {},
    { headers: { Authorization: `Bearer ${<PORTAL_API_KEY>}` } }
);
const clientSessionToken = response.data.clientSessionToken;
const clientId = response.data.id;
```

<Warning>
  Ensure the **`clientId`** is stored securely as it is crucial for future operations.
</Warning>

#### Subsequent Logins

When the token needs refreshing (during later logins), use the following endpoint:

```typescript theme={null}
const response = await axios.post(
    `https://api.portalhq.io/api/v1/custodians/clients/${clientId}/session`,
    {},
    { headers: { Authorization: `Bearer ${<PORTAL_API_KEY>}` } }
);
const refreshedClientSessionToken = response.data.clientSessionToken;
```

Your user can now use this refreshed `clientSessionToken`.

<Note>
  When your user's CST expires, all Portal SDKs will throw an error on the next MPC Operation the user makes (e.g. creating a wallet, backing up a wallet, recovering a wallet, or signing). That error will include [the error code **`INVALID_API_KEY`**](./error-codes) in the SDK methods, which you can use as an indicator to refresh your CST.
</Note>