Getting started

This guide will guide you through the basics of the usage of our API. By the end of reading through this guide you will be equipped by the knowledge of how to implement API requests to any of your endpoints.

For development purposes we recommend any tool that supports GraphQL exploration, here are a few of them:

Environments in Eneba API

Eneba API provides two environments: sandbox and production. We highly recommend testing your API integration in the sandbox environment first. This is a safe way to avoid unintentional purchases, charges, or lost keys.

The difference between the two of them is the base URL and credentials used. Please use the following base URL while making HTTP requests:

https://api-sandbox.eneba.com/graphql/

Regarding credentials, reference the next section.

Getting Access

Eneba API uses OAuth 2.0 authorization mechanism with Bearer tokens. If you are not familiar with OAuth, please read more on OAuth Access Tokens and Refreshing OAuth Access Tokens.

1. Getting the credentials

You can get your credentials from the Eneba dashboard.

2. Authentication

After you have generated the sandbox or production credentials, you need to get an access_token. To get it, you will have to use the Auth ID and Auth Secret values you got in the "Getting the credentials" step above.

The following describes how you can get an access token for sandbox or production environments.

Request parameters:

FieldValue
urlhttps://api-sandbox.eneba.com/oauth/token
methodPOST
Content-Typeapplication/x-www-form-urlencoded

Request body:

FieldValue
client_id917611c2-70a5-11e9-00c4-ee691bb8bfaa
grant_typeapi_consumer
idAuth ID value from the Eneba dashboard
secretAuth Secret value from the Eneba dashboard

Example request:

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=api_consumer&client_id=917611c2-70a5-11e9-00c4-ee691bb8bfaa&id={Auth-ID}&secret={Auth-Secret}" \
https://api-sandbox.eneba.com/oauth/token

Example response:

{
    "token_type": "Bearer",
    "expires_in": 216000,
    "access_token": "eyJXAiNiJ9.eyJhdWOYS5jb20ifQ.KOQQxuzLY",
    "refresh_token": "44c6d767755aeb3851908a2f1d"
}

Note that the authentication response on sandbox does not have the refresh_token.

3. Using the access token

All requests to our GraphQL API must contain a Bearer access token in the Authorization HTTP header. Use the access_token you acquired in step #2 as follows:

Authorization: Bearer <access_token>

The acquired access_token is temporary and will expire after the expires_in time passes. You will need to implement the OAuth token refresh flow in order to keep the API implementation secure.

It is not recommended to run Authentication before every request. This may result in rate-limiting rules applied to your entire IP. The following section describes rate limiting in more detail.

Rate limiting

To protect internal systems, Eneba API implements rate-limiting. There are two types of rate-limiting strategies - global and action.

Global limits

Your IP address is limited to 5000 requests per 10 min.

Solution to global limits

Eneba uses GraphQL for its API this allows to batch multiple GraphQL requests into a single HTTP request.

Example:

We need to update the price of all our auctions.

Classical approach

In a classical API we would have to perform two HTTP requests and update the price one-by-one:

mutation {
  S_updateAuction(
    input: {
      id: "0c000bd0-5109-147a-ac7f-ca90e75ca652"
      price: { amount: 1100 currency: "EUR" }
    }
  ) {
    isSuccessful actionId
  }
}
mutation {
  S_updateAuction(
    input: {
      id: "26d8a2a1-5dee-147a-ac7f-ca88a25ca05f"
      price: { amount: 199 currency: "EUR" }
    }
  ) {
    isSuccessful actionId
  }
}
Batched GraphQL approach

Now, if we would use batched requests feature, we could send a single HTTP request:

mutation updateAuction_1 {
  S_updateAuction(
    input: {
      id: "0c000bd0-5109-147a-ac7f-ca90e75ca652"
      price: { amount: 1100 currency: "EUR" }
    }
  ) {
    isSuccessful actionId
  }
}

mutation updateAuction_2 {
  S_updateAuction(
    input: {
      id: "26d8a2a1-5dee-147a-ac7f-ca88a25ca05f"
      price: { amount: 199 currency: "EUR" }
    }
  ) {
    isSuccessful actionId
  }
}

What we added here is the names for individual GraphQL requests.

You can read more about batched requests in Apollo Graphql docs.

Action limits

Some actions are protected by specific limits:

ActionRate limit
S_updateAuction1 request per 3 sec.
B_balance2 requests per 1 min.
C_announcements2 requests per 1 min.

Solution to action limits

Make all changes in a single GraphQL request.

Example:

We need to enable particular auction and update its price.

Instead of making two separate requests to enable the auction and to update its price, we can use a single GraphQL request and make such modifications in one go:

mutation {
  S_updateAuction(
    input: {
      id: "26d8a2a1-5dee-147a-ac7f-ca88a25ca05f"
      price: { amount: 199 currency: "EUR" }
      enabled: true
    }
  ) {
    isSuccessful actionId
  }
}
Copyright 2024 Eneba. All Rights Reserved. JSC “Helis play”, Gyneju St. 4-333, Vilnius, the Republic of Lithuania