API Key and Session Tokens

At this section we describe how to work with API Keys and Session Tokens API

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.

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.

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.

Request

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

Success Response

{
  "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
      }
    }
  ]
}

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.

Request

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

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

Success Response

{
  "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
    }
  }
}

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

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.

Get API Key by ID

Method to get information about the API Key by ID.

Request

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

Success Response

{
  "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
    }
  }
}

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.

Request

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

Success Response

Status: 204 No Content

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:

Request

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

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

Response

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

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.