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

# Authenticate to the Gcore API

> Create a Gcore token, set it as an environment variable, and verify it to authenticate requests.

Every Gcore API request requires an API token. The token goes in the `Authorization` header and works across all products — Cloud, CDN, DNS, Storage, and others.

## Step 1. Create a token

1. Sign in to the [Gcore Customer Portal](https://portal.gcore.com).
2. Click the account icon in the top-right corner and navigate to **Profile**.
3. Select the **API tokens** tab.
4. Click **Create token**.
5. Give the token a name, select a role (use `Administrators` for full access), and set an expiration date if needed.
6. Click **Create**. A dialog shows the token value — copy it before closing. It will not be shown again.

> [!NOTE]
>
> The token value is shown only once — store it somewhere secure (a password manager or secrets vault) before closing the dialog.

## Step 2. Set an environment variable

Store the token in an environment variable so it can be used in every command without re-typing or hardcoding it in scripts.

Open a terminal and run:

```bash theme={null}
export GCORE_API_KEY="29841_c767..."
```

Replace `29841_c767...` with the actual token value copied in Step 1.

> [!NOTE]
>
> Environment variables are session-scoped — they disappear when the terminal is closed, so to persist across sessions, add the `export` line to `~/.zshrc` (macOS/Linux) or the PowerShell profile file (Windows).
>
> Not sure what these concepts mean? [API basics](/developer-tools/rest-api/api-basics) covers terminals and environment variables from scratch.

## Step 3. Verify the token

Confirm the token is valid and see which account it belongs to:

**curl**

```bash theme={null}
curl "https://api.gcore.com/iam/clients/me" \
  -H "Authorization: APIKey $GCORE_API_KEY"
```

The API returns:

```json theme={null}
{
  "id": 7350925,
  "email": "user@example.com",
  "status": "active",
  "currentUser": 1023101
}
```

**Python SDK**

```python theme={null}
from gcore import Gcore

client = Gcore()  # SDK reads GCORE_API_KEY automatically
me = client.iam.get_account_overview()
print(me.id, me.email, me.status)
```

**Go SDK**

```go theme={null}
import (
    "context"
    "fmt"
    gcore "github.com/G-Core/gcore-go"
)

client := gcore.NewClient()
ctx := context.Background()
me, err := client.Iam.GetAccountOverview(ctx)
if err != nil { panic(err) }
fmt.Println(me.ID, me.Email, me.Status)
```

**JavaScript**

```javascript theme={null}
const res = await fetch("https://api.gcore.com/iam/clients/me", {
  headers: { Authorization: `APIKey ${process.env.GCORE_API_KEY}` },
});
const me = await res.json();
console.log(me.id, me.email, me.status);
```

If the response shows `"status": "active"` and contains an email address, the token is working.

## Common authentication errors

If the command returns an error instead, the table below shows the most common causes:

| Error message | Cause | Fix |
| - | - | - |
| `Authentication credentials were not provided.` | No `Authorization` header sent | Check that `-H "Authorization: APIKey $GCORE_API_KEY"` is present |
| `Bad token: 29841` | Token value is incomplete | Verify the full token value was copied correctly in Step 1 |
| `Token is invalid or expired` | Token was deleted or has passed its expiry date | Create a new token in the portal |
| `Given token not valid for any token type` | Using `Bearer` instead of `APIKey` | The scheme must be `APIKey`, not `Bearer` |

The `Authorization` header name is case-insensitive — `Authorization`, `authorization`, and `AUTHORIZATION` all work — while the `APIKey` prefix is not optional.

***

## Token roles

When creating a token, a role is assigned that controls what the token can do:

| Role | Access level |
| - | - |
| Administrators | Full read and write access to all resources |
| Engineers | Technical operations; no billing or user management |
| Users | Read access to most resources; limited write access |

A token cannot have a higher role than the user who created it. For automation that creates and deletes infrastructure, `Administrators` is typically required.

## Token expiration and limits

* Maximum 50 tokens per account.
* Tokens expiring within 7 days trigger email notifications at 7 days and 1 day before expiry.
* To rotate a token, create a new one first, update all integrations, then delete the old one.

## SSO accounts

When signing in via SAML SSO, the identity provider controls portal access but API tokens operate independently, so revoking a user's SSO access does not invalidate their tokens. To block API access for an SSO user, delete their tokens manually in the [API tokens](/account-settings/api-tokens) section.