Octopus Energy Germany

The Kraken API is made up of the following services:

• The "API site" containing both REST and GraphQL APIs: api.oeg-kraken.energy
• An authentication server: auth.oeg-kraken.energy

This section provides general guidance on how to use the API site's GraphQL API. For more information on what is available on the GraphQL schema, see the GraphQL reference docs. Documentation on our other services can be found at the links below:

• REST API
• Authentication server

Making requests

All GraphQL requests should be made over HTTPS using the following base URL: https://api.oeg-kraken.energy/v1/graphql/.

A GraphQL IDE is available at https://api.oeg-kraken.energy/v1/graphql/. Here you are able to make requests via the browser, access schema documentation and use tools which surface Kraken-specific features. For any query, the following information is available:

• the permissions required to make the query
• possible errors that the query could return
• the complexity of the query
• what rate limits are in place for the query

Errors

Unlike our REST API, the GraphQL API will always return a 200 response code, assuming the server is available. If there is an error, this will be returned in the "errors" field of the response alongside an error code, type and description, for example:

See the error codes reference for a full list of error codes.

The possible errors that a Query or Mutation can return are also documented in the description for the relevant field in the reference documentation or via the 'Possible errors' tab in the GraphQL IDE.

Note that the different errors that a request raises may vary depending on the specific fields requested.

Authentication

Authentication is required for some queries and mutations. This is performed via setting the Authorization header for requests to be the appropriate token for a user. You can get a token for your user by using the ObtainKrakenToken Mutation. This Mutation has several different ways to authenticate, including email/password, an API key, or a pre-signed key.

When you have your token, you can set the Authorization header in the client you are using to make the request. The header should be set to the value of your token. For example, if your token is 12345, you would set the Authorization header to 12345.

{ "Authorization": "12345" }

The token is only valid for 60 minutes from time of issuance. However, the refreshToken is valid for 7 days (you can use the refreshExpiresIn value to know when the refreshToken will expire). The recommended usage is: cache both token and refreshToken based on their expiry time, and use the cached token to make API requests; regenerate the token when it expires using the ObtainKrakenToken Mutation, authenticating with the refreshToken; re-request both tokens using the ObtainKrakenToken Mutation with the original authentication method when the refreshToken expires.

Deprecations

Occasionally, fields and arguments become outdated, and we may mark them as deprecated. In these cases, the field will be visibly deprecated on the schema, and a deprecation reason will be provided on the item's description on the schema. The deprecation reason will likely point to the new type that should be used instead.

Pagination

Some fields in the API return a list of objects. These are paginated and the pagination information is returned in the pageInfo field of the response. The pageInfo object contains the hasNextPage and hasPreviousPage fields which indicate if there are more pages of results. The startCursor and endCursor fields contain the cursors for the first and last objects in the current page of results. The cursors can be used to paginate through the results.

For example, this is a query for getting account transactions with pagination:

query getTransactions($accountNumber: String!) { account(accountNumber: $accountNumber) { transactions(first: 10, after: "<some-cursor>") { pageInfo { hasNextPage hasPreviousPage startCursor endCursor } edges { cursor node { id } } } } }

Note that when using pagination the hasNextPage and hasPreviousPage fields have slightly unintuitive behaviour. Where if you are paginating forward using the after argument, the hasPreviousPage field will always be false which is behaviour defined in the GraphQL Relay spec. If you would like to read more about this behaviour, please see the PageInfo section of the spec. For fields that have pagination we enforce that pagination is used and that the first argument is set to a value less than 100. If you do not set the first argument, or set it to a value greater than 100, you will receive an error.

Usage constraints

This section details the features in place on our GraphQL API to ensure that our services remain available and performant.

Limiting the complexity of a query

Each GraphQL field has a complexity value assigned to it and each request must stay within the complexity limit. The complexity limit for a single request is 200. If the total complexity of a request exceeds the limit, the viewer will receive an error with code KT-CT-1188 in the response.

See the complexity of each field in a request and the overall complexity of the request in the "Query complexity" tab of the GraphQL IDE.

Hourly points allowances

We also use the complexity of each field to determine the maximum number of 'points' which a viewer is allowed to consume per hour.

The total number of 'points' used within an hour must not exceed the total allowed limit, even when individual requests are within their complexity limits. This feature applies to authenticated viewers, i.e organisations, account users and OAuth applications, and can be set to one of the following modes:

• COUNT: only monitor the number of points requested, without limiting it
• BLOCK (default): block requests when the maximum number of points is exceeded
• DENY_LIST: only block specific viewers from making requests that would exceed the maximum number of points

Hourly points allowances can be configured for organisations and account users via the Kraken Hub. The default values are:

• Account users: 50,000 points
• Organisations: 100,000 points
• OAuth applications: 300,000 points

Information about the points limit or remaining balance for an authenticated viewer can be fetched using the rateLimitInfo query.

Scaling points allowances according to supply points

For account users who manage multiple supply points, Kraken implements a dynamic approach which automatically scales a user's points allowance based on the number of supply points under management. This feature is particularly beneficial for:

• Commercial and Industrial (C&I) customers responsible for numerous supply points
• Business users who need to perform operations across multiple locations
• Users who require frequent API access to manage large portfolios

Request-specific rate limiting

Request-specific rate limiting is focused on protecting specific GraphQL fields from being overloaded, especially those which don't require authentication.

Request-specific rate limits restrict the number of calls which can be made from the same IP address, user or other identifying factor within a specific period of time. For example, to prevent credential stuffing attacks, we could use a rate limit which means that a single IP address can only request to log in 5 times within a minute.

When rate limited, the viewer will receive the KT-CT-1199 error code indicating they have made too many requests.

There are two types of request-specific rate limiting:

• Static: if, for example, a static rate limit of 100 requests per minute is applied to a field, when a user exceeds this limit they will be blocked from making requests until the minute has passed. Once the minute is over, they will be able to call the field again with the same rate of 100 requests per minute.
• Dynamic: dynamic rate limits become progressively stricter if repeatedly exceeded. For example, if there is an initial limit of 100 requests per minute, each time a viewer breaks this limit, the number of subsequent calls they can make reduces until they may reach a limit of 1 request per hour.

Note, dynamic rate limits do not automatically reset to their original values. If needed, an admin can assist in unblocking a viewer manually and re-setting their limit via the Kraken Hub.

See what rate limits are applied to fields in a request via the "Rate limits" tab of the GraphQL IDE.

Information about the rate limits currently being applied to a particular IP address or viewer can be fetched using the rateLimitInfo query.

Limiting the number of nodes requested

To ensure our API remains performant, we limit the total number of items ('nodes') that can be requested in a single GraphQL query. This limit is: 10,000 nodes per request.

Viewers will receive error code KT-CT-1189 ("Query exceeds maximum allowed node count") when exceeding the maximum nodes per request limit.