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