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

# Authenticate to the Gcore API

Every Gcore API request requires a permanent 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. Open the [Gcore Customer Portal](https://portal.gcore.com) and sign in.
2. Click the account icon in the top-right corner and go to **Profile**.
3. Select the **API tokens** tab.
4. Click **Create token**.
5. Give the token a name, choose 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.

<Info>
  The token value is shown only once — store it somewhere secure (a password manager or secrets vault) before closing the dialog.
</Info>

## Step 2. Set the token as 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.

<Info>
  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.
</Info>

## Step 3. Verify the token

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

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

  <Tab title="Python SDK">
    ```python theme={null}
    import os
    from gcore import Gcore

    client = Gcore(api_key=os.environ["GCORE_API_KEY"])
    me = client.iam.get_account_overview()
    print(me.id, me.email, me.status)
    ```
  </Tab>

  <Tab title="Go SDK">
    ```go theme={null}
    import (
        "context"
        "fmt"
        "os"
        gcore "github.com/G-Core/gcore-go"
        "github.com/G-Core/gcore-go/option"
    )

    client := gcore.NewClient(option.WithAPIKey(os.Getenv("GCORE_API_KEY")))
    me, err := client.Iam.GetAccountOverview(context.TODO())
    if err != nil { panic(err) }
    fmt.Println(me.ID, me.Email, me.Status)
    ```
  </Tab>

  <Tab title="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);
    ```
  </Tab>
</Tabs>

A successful response looks like:

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

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 permanent 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 permanent 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.