# API Key and Session Tokens

## API Key

As we mentioned before, an API Key is an authentication sign method which should be used to make requests to the Vaulera PCI API endpoints.

{% hint style="warning" %}
You should protect your API Keys to prevent leaks. Don’t store API Keys in your Source Code and limit the count of people who have access to the API Keys.
{% endhint %}

### API Key Structure

API Key is represented with the next fields:

`id` unique identifier based at UUID v.4\
`api_key` API Key value (Masked)\
`description` String field with custom human readable notes about API Key if provided (Can be used to show where this key is used)\
`status` Enumerable field with 2 possible values (active, revoked). If key is active you can use it to perform operations.\
`created_at` Timestamp, when API Key was created.\
`revoked_at` Timestamp, when API Key was revoked.

### Get list of API Keys

Method to get list of existing API Keys associated with the account.

{% tabs %}
{% tab title="Request" %}

```
GET https://pci.vaultera.co/api/v1/api_keys?api_key={YOUR_API_KEY}
```

{% endtab %}

{% tab title="Success Response" %}

```javascript
{
  "data": [
    {
      "id": "4cdced9e-31ef-4f36-ad9a-3c9512f5646e",
      "type": "api_key",
      "attributes": {
        "id": "4cdced9e-31ef-4f36-ad9a-3c9512f5646e",
        "api_key": "...4a39b3",
        "description": "Application key",
        "status": "active",
        "created_at": "2020-06-08T05:49:10.979Z",
        "revoked_at": null
      }
    }
  ]
}
```

{% endtab %}
{% endtabs %}

Method will return success result with code `200 OK` and list of `api_key` under data node.

### Create API Key

Method to create a new API Key.

{% tabs %}
{% tab title="Request" %}

```
POST https://pci.vaultera.co/api/v1/api_keys?api_key={YOUR_API_KEY}

{
  "api_key": {
    "description": "API KEY description"
  }
}
```

{% endtab %}

{% tab title="Success Response" %}

```javascript
{
  "data": {
    "id": "4cdced9e-31ef-4f36-ad9a-3c9512f5646e",
    "type": "api_key",
    "attributes": {
      "id": "4cdced9e-31ef-4f36-ad9a-3c9512f5646e",
      "api_key": "4cdced9e31ef4f36ad9a4a39b3",
      "description": "Application key",
      "status": "active",
      "created_at": "2020-06-08T05:49:10.979Z",
      "revoked_at": null
    }
  }
}
```

{% endtab %}
{% endtabs %}

Method will return success result with code `200 OK`. Response will contain `api_key` structure.

{% hint style="warning" %}
API Key will be visible only at this response, all other methods will not show the API Key again. The API Key will be automatically generated and show once only.
{% endhint %}

### Get API Key by ID

Method to get information about the API Key by ID.

{% tabs %}
{% tab title="Request" %}

```
GET https://pci.vaultera.co/api/v1/api_keys/{id}?api_key={YOUR_API_KEY}
```

{% endtab %}

{% tab title="Success Response" %}

```javascript
{
  "data": {
    "id": "4cdced9e-31ef-4f36-ad9a-3c9512f5646e",
    "type": "api_key",
    "attributes": {
      "id": "4cdced9e-31ef-4f36-ad9a-3c9512f5646e",
      "api_key": "...4a39b3",
      "description": "Application key",
      "status": "active",
      "created_at": "2020-06-08T05:49:10.979Z",
      "revoked_at": null
    }
  }
}
```

{% endtab %}
{% endtabs %}

Method will return success result with code `200 OK`. Response will contain `api_key` structure.

### Revoke API Key

Method to revoke API Key. After this action, each request signed by a revoked key will fail and return an Authorization error.

{% tabs %}
{% tab title="Request" %}

```
DELETE https://pci.vaultera.co/api/v1/api_keys/{id}?api_key={YOUR_API_KEY}
```

{% endtab %}

{% tab title="Success Response" %}

```javascript
Status: 204 No Content
```

{% endtab %}
{% endtabs %}

Method will return success result with code `204 No Content`. Response will contain `api_key` structure.

## Session Token operations

Embedded operations at Vaultera PCI will expect to receive a `Session Token` as an authorization sign. To generate a `Session Token`, you can use the next method:

{% tabs %}
{% tab title="Request" %}

```
POST https://pci.vaultera.co/api/v1/session_tokens?api_key={YOUR_API_KEY}

{
  "session_token": {
    "scope": "show_card"
  }
}
```

{% endtab %}

{% tab title="Response" %}

```javascript
{
  "data": {
    "id": "string",
    "type": "session_token",
    "attributes": {
      "session_token": "string",
      "scope": "show_card"
    }
  }
}
```

{% endtab %}
{% endtabs %}

Please, take a look at the scope argument, it represents how you can use the created `Session Token`. The scope allows 3 values: `card`, `show_card` and `show_service_code`.

If `Session Token` is created with scope `card` you can use it to capture card information.

If `Session Token` is created with scope `show_card` you can use it to get the card information, but does not include the `Service Code` for this card.

If `Session Token` is created with scope `show_service_code` you will only see the `Service Code` and not the card details.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.vaultera.co/api-key-and-session-tokens.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.