> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.definitely.live/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.definitely.live/_mcp/server.

# Authentication & Security

The Plant Store API provides robust authentication mechanism options depending on the type of operation and client application:

1. **API Key Authentication**: For server-to-server store operations, inventory queries, and administrative management.
2. **OAuth2 Authorization**: For user-delegated plant management operations and third-party app integrations.

---

## Authentication Schemes

| Scheme            | Header / Location                        | Scope / Usage                | Required For                                                   |
| ----------------- | ---------------------------------------- | ---------------------------- | -------------------------------------------------------------- |
| **API Key**       | `api_key: <YOUR_API_KEY>` (Header)       | Store & Inventory operations | Placing orders, querying store inventory, reading user details |
| **OAuth2 Bearer** | `Authorization: Bearer <TOKEN>` (Header) | User-scoped plant operations | Adding plants, modifying plant records, deleting items         |

---

## 1. API Key Authentication

API Keys are suitable for backend servers, daemon services, and server-side applications.

### Sending the API Key

Include the `api_key` header in all HTTP requests targeting protected store endpoints:

```bash title="cURL"
curl -X GET "https://api.plantstore.dev/v3/store/inventory" \
  -H "api_key: pk_live_98f7d6a5e4c3b2a1" \
  -H "Accept: application/json"
```

```python title="Python (SDK)"
from plantstore import PlantStore

client = PlantStore(api_key="pk_live_98f7d6a5e4c3b2a1")
inventory = client.store.get_inventory()
print(inventory)
```

```typescript title="Node.js (SDK)"
import { PlantStoreClient } from "@plantstore/sdk";

const client = new PlantStoreClient({ apiKey: "pk_live_98f7d6a5e4c3b2a1" });
const inventory = await client.store.getInventory();
```

**Keep your API Keys secret.** Never check API keys into client-side code, public GitHub repositories, or mobile app bundles. Use environment variables (e.g. `PLANTSTORE_API_KEY`) on your server.

---

## 2. OAuth2 Authorization

For operations modifying plant records, the API supports OAuth 2.0 with the following scopes:

* `write:plants`: Grants permission to create, edit, and update plant entries.
* `read:plants`: Grants permission to view private or draft plant catalog entries.

### OAuth2 Authorization Code Flow

```mermaid
sequenceDiagram
    autonumber
    actor User
    participant Client as App Client
    participant AuthServer as Plant Store Auth Server
    participant ResourceServer as Plant Store API

    User->>Client: Click "Connect Plant Store"
    Client->>AuthServer: Redirect to /oauth/authorize?response_type=code&scope=write:plants
    AuthServer->>User: Display consent prompt
    User->>AuthServer: Approve access permissions
    AuthServer->>Client: Redirect to callback URL with auth code (?code=AUTH_CODE)
    Client->>AuthServer: POST /oauth/token (code + client_secret)
    AuthServer->>Client: Return Access Token + Refresh Token
    Client->>ResourceServer: GET /v3/plant/123 with Authorization: Bearer <TOKEN>
    ResourceServer->>Client: Return requested plant data
```

---

## Error Handling & Status Codes

When authentication fails or credentials are missing, the API returns consistent JSON error payloads:

```json title="401 Unauthorized Response"
{
  "code": 401,
  "type": "AUTHENTICATION_FAILED",
  "message": "Invalid or expired API Key provided in header 'api_key'."
}
```

```json title="403 Forbidden Response"
{
  "code": 403,
  "type": "INSUFFICIENT_SCOPE",
  "message": "Token does not possess required scope 'write:plants' for action DELETE /v3/plant/100."
}
```

---

## Security Best Practices

#### Rotate keys periodically

Generate new API keys every 90 days from the developer console to minimize credential compromise risks.

#### Enforce TLS 1.3

All API traffic MUST use HTTPS (`https://api.plantstore.dev`). Plain HTTP requests will automatically receive a `301 Permanently Redirected` response.

#### Use scoped OAuth tokens

For client-facing applications, request only the minimum required OAuth scopes (e.g. `read:plants` rather than administrative scopes).