Authentication

The Gradient API uses API keys to authenticate requests. You can view and manage your API keys in the Gradient Dashboard.

Using Your API Key

Include your API key in the Authorization header as a Bearer token:

curl https://essence-api.gradientgroup.com/v1/jobs \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Request

Here's a complete example of an authenticated request:

cURL

curl -X GET https://essence-api.gradientgroup.com/v1/jobs \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Content-Type: application/json"

JavaScript

const response = await fetch('https://essence-api.gradientgroup.com/v1/jobs', {
  headers: {
    'Authorization': 'Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();

Swift

import Foundation

let url = URL(string: "https://essence-api.gradientgroup.com/v1/jobs")!
var request = URLRequest(url: url)
request.httpMethod = "GET"
request.setValue("Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc", forHTTPHeaderField: "Authorization")
request.setValue("application/json", forHTTPHeaderField: "Content-Type")

let task = URLSession.shared.dataTask(with: request) { data, response, error in
    guard let data = data else {
        print("Error: \(error?.localizedDescription ?? "Unknown error")")
        return
    }
    
    if let json = try? JSONSerialization.jsonObject(with: data) {
        print(json)
    }
}

task.resume()

Security Best Practices

Store API keys in environment variables, not in your code
Use different keys for development and production
Never commit API keys to version control

Error Responses

Authentication errors will return a 401 status code:

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or has been revoked"
  }
}