---
title: API concepts and authentication
description: Contracts, permissions, errors and safe examples.
product: docs
product_version: 0.1.0
api_version: null
locale: en
type: concept
classification: PUBLIC
lifecycle: stable
owner: miloslav-hub
licence: CC-BY-4.0
slug: api-concepts
---

## Public descriptions and API access

A public reference can describe an API that requires authentication. Reading its documentation grants no permission to call it.
Each service owns its client keys, scopes, limits and lifecycle. Follow that service’s instructions to obtain access.

## OpenAPI

OpenAPI describes operations, inputs, responses and security schemes. Its machine-readable contract has its own version.
Changing the renderer does not change the API. A draft contract is not evidence of a deployed implementation.

## Safe examples

This example uses an inactive hostname and placeholder token; it sends nothing to production:

```http
GET /example-items HTTP/1.1
Host: api.example.invalid
Authorization: Bearer EXAMPLE_TOKEN_DO_NOT_USE
```

Store real keys securely in the relevant server-side client, never in a public website or documentation.

## Errors and limits

401 usually indicates missing or invalid authentication; 403 indicates insufficient permissions. A service can return 429 when a limit is exceeded.
Follow the actual error format and retry rules of the API. Do not include sensitive data, tokens or internal stack traces in public issue reports.
