API Overview

Introduction

The Render Compute API is structured as a REST API that uses resource-oriented URLs. It accepts JSON-encoded request bodies and returns JSON-encoded responses. All API requests must be made using HTTPS protocol.

API Reference

The Render Compute API serves OpenAPI JSON documentation.

The OpenAPI specification describes the available API endpoints, and outlines the schemas for valid request bodies, query parameters, and JSON responses.

Authentication

API Keys

The Render Compute API primarily uses API keys to authenticate requests.

API keys are privileged credentials; they should be handled securely. Do not share your secret API keys publicly, and take care to not commit them to your source code or accidentally include them in any client-side code bundles.

Note

If you are authenticating with an API key, you must include your API key public_key in the X-API-Key header.

JSON Web Tokens

The Render Compute API may also use JSON Web Tokens (JWT) to authenticate requests. JWTs are issued by the Render Compute API and can be used to authenticate requests to the API. You can find the JSON Web Key Set (JWKS) at the /.well-known/jwks endpoint.

Note

If you are authenticating with a JWT, the JWT must be included in the Authorization header of the request as a Bearer token.

Request Headers

The Render Compute API requires a set of request headers in order to ensure the integrity of requests between clients and the API. They are as follows:

X-Time

The X-Time header must be a UTC timestamp in milliseconds. It must be generated by the client per-request and it must be within 5 minutes of the server time.

X-Nonce

The X-Nonce header must be a 32-character hexadecimal string. It must be generated by the client per-request and it must be unique for each request.

X-Signature

The X-Signature header must be a hex-encoded sha256 HMAC signature of the canonical parameters of the request. It must be generated by the client per-request.

The HMAC signature must be derived from a string composed of the following canonical parameters, in order, delimited by a pipe | character:

1. Public Key / HMAC Key
   • If you are authenticating using an API key, this must be the same public key as your X-API-Key header.
   • If you are authenticating using a JWT, this must be the same as your JWT hmac_key claim.
2. Timestamp
   • The UTC timestamp in milliseconds. This must be the same as your X-Time header.
3. Nonce
   • The 32-character hexadecimal string nonce. This must be the same as your X-Nonce header.
4. Method
   • The HTTP request method, in uppercase (e.g. GET).
5. Path
   • The HTTP request path e.g. /v1/jobs.
6. Query
   • The URL query string with no leading ? character, e.g. status=COMPLETED. If there are no query parameters, this should be an empty string.
7. Body SHA256
   • A hex-encoded sha256 hash digest of the request body bytes, if any.
   • If there is no request body, this should be a sha256 hash of an empty byte array.
   • If there is a JSON request body, it must be canonicalized with sorted keys and no whitespace before byte-encoding.

Example:

{public_key}|{timestamp}|{nonce}|{method}|{path}|{query}|{body_sha256}

The HMAC signature must be signed using the sha256 algorithm and the HMAC secret key must be the same as either:

• The secret_key of your API key credential, or
• The hmac_key claim of your JWT