Authentication

Authentication Format

The X-API-KEY header must follow this format:

X-API-KEY: <YOUR_API_KEY>

Example (Using cURL)

curl -X GET "https://api.ocus.io/v3/projects" \\
	-H "X-API-KEY: <YOUR_API_KEY>"

Example (Using JavaScript/Node.js)

import axios from 'axios';

axios.get('https://api.ocus.io/v3/projects', {
  headers: {
    X-API-KEY: '<YOUR_API_KEY>',
  },
})
  .then(response => console.log(response.data))
  .catch(error => console.error(error));

// not a go developer, might be wrong since it's generated by chat gpt
package main

import (
	"fmt"
	"io/ioutil"
	"net/http"
)

func main() {
	client := &http.Client{}
	req, err := http.NewRequest("GET", "https://api.example.com/v1/resource", nil)
	if err != nil {
		fmt.Println("Error creating request:", err)
		return
	}

	req.Header.Set("Authorization", "apikey abc123xyz")

	resp, err := client.Do(req)
	if err != nil {
		fmt.Println("Error making request:", err)
		return
	}
	defer resp.Body.Close()

	body, err := ioutil.ReadAll(resp.Body)
	if err != nil {
		fmt.Println("Error reading response body:", err)
		return
	}

	fmt.Println(string(body))
}

Security Best Practices for Clients

One key per system:

Do not share an API key between multiple systems or environments.
Store Keys Securely:

Save your API key in a secure location, such as an environment variable or a secrets manager. Avoid hardcoding it in your codebase.
Rotate Keys Regularly:

Periodically generate new API keys and deprecate older ones to enhance security.
Use HTTPS:

Always access the API over HTTPS to prevent your API key from being intercepted.

Example Error Responses

Missing or Invalid Key

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
	"error": "Unauthorized. Please provide a valid API key."
}

Revoked or Expired Key

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
	"error": "Forbidden. This API key has been revoked or expired."
}