Authentication

Authentication is performed at the HTTP level. Every GraphQL request—whether it contains a query or a mutation—must include the following two headers:

X-AUTH-KEY: <your-api-key>
X-AUTH-SECRET: <your-api-secret>

Both headers are required to identify and authenticate the integration making the request. The GraphQL schema itself confirms the same authentication mechanism for queries and mutations.

How authentication works

GraphQL operations are sent to the API endpoint assigned to your integration. The GraphQL operation itself does not contain authentication information. Instead, the credentials are transmitted as HTTP headers together with the request.

A request therefore consists of two separate parts:

1. HTTP request information, including the authentication headers.
2. GraphQL operation, containing the query or mutation you want to execute.

For example:

POST <your-graphql-endpoint>
Content-Type: application/json
X-AUTH-KEY: <your-api-key>
X-AUTH-SECRET: <your-api-secret>

The request body then contains the GraphQL operation:

{
  "query": "query { salesOrders(limit: 10) { totalCount } }"
}

The credentials authenticate the integration, while the GraphQL query defines which data should be requested.

Your API endpoint and integration-specific connection information are provided as part of the onboarding and integration setup.

API key and API secret

Authentication consists of a pair of credentials:

X-AUTH-KEY

The API key identifies the API integration.

X-AUTH-KEY: your-api-key

X-AUTH-SECRET

The API secret proves that the request originates from a client authorized to use that integration.

X-AUTH-SECRET: your-api-secret

The key and secret must be sent together with every authenticated request.

Do not include either value inside the GraphQL query or mutation itself.

Sessionless authentication

The returns.cloud GraphQL API intentionally uses a sessionless authentication model.

There is no separate login request and no authentication session that your application needs to create, maintain, refresh, or terminate. Instead, every API request is authenticated independently using the same X-AUTH-KEY and X-AUTH-SECRETheaders.

This keeps the integration flow simple:

Application
    │
    │  GraphQL request
    │  + X-AUTH-KEY
    │  + X-AUTH-SECRET
    ▼
returns.cloud GraphQL API

Your application therefore does not need to:

• request an access token before using the API
• store a temporary session token
• track token expiration
• implement token refresh logic
• retry requests because an authentication session expired
• maintain authentication state between API requests

Each request contains everything required for authentication.

This is particularly useful for server-to-server integrations, scheduled synchronization jobs, queue workers, and other backend processes where requests may be executed independently or across multiple application instances.

Example request

A complete request could look like this:

curl --request POST \
  --url '<your-graphql-endpoint>' \
  --header 'Content-Type: application/json' \
  --header 'X-AUTH-KEY: <your-api-key>' \
  --header 'X-AUTH-SECRET: <your-api-secret>' \
  --data '{
    "query": "query { salesOrders(limit: 10) { totalCount } }"
  }'

After authentication, the request is handled like any other GraphQL operation. The API validates the query against the schema and returns the requested data or an error.

The same authentication headers are used for mutations:

curl --request POST \
  --url '<your-graphql-endpoint>' \
  --header 'Content-Type: application/json' \
  --header 'X-AUTH-KEY: <your-api-key>' \
  --header 'X-AUTH-SECRET: <your-api-secret>' \
  --data '{
    "query": "mutation { ... }"
  }'

There is no separate authentication method for reading and writing data. Queries and mutations use the same integration credentials.

Credentials belong to the integration

Treat the credentials as integration credentials rather than user credentials.

They are intended for communication between your system and returns.cloud—for example, your ERP, shop platform, middleware, warehouse system, or another backend application.

This also means that the credentials should normally be stored and used on the server side rather than exposed to browsers or other client-side applications.

Authentication and GraphQL introspection

Authentication also applies when you use GraphQL introspection.

The Introspection Query is a normal GraphQL query. Therefore, the client performing the introspection must authenticate against the API in the same way as any other request.

Troubleshooting authentication

If a request cannot be authenticated, first verify that:

• both X-AUTH-KEY and X-AUTH-SECRET are included
• the exact header names are used
• the credentials belong to the integration you are calling
• the correct GraphQL endpoint is being used
• no whitespace, quotation marks, or other characters were accidentally added to the credential values
• your HTTP client is actually sending the custom headers

A useful first test is to execute a simple query in GraphiQL with the same credentials. If the request works there but not in your application, compare the HTTP headers sent by both clients.

Next steps

Once authentication is working, continue with API Exploration to learn how to use GraphiQL, SpectaQL, and GraphQL introspection to explore the API schema.