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

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:

$
curl -X GET "https://api.plantstore.dev/v3/store/inventory" \
>
  -H "api_key: pk_live_98f7d6a5e4c3b2a1" \
>
  -H "Accept: application/json"

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

Error Handling & Status Codes

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

1
{
2
  "code": 401,
3
  "type": "AUTHENTICATION_FAILED",
4
  "message": "Invalid or expired API Key provided in header 'api_key'."
5
}

1
{
2
  "code": 403,
3
  "type": "INSUFFICIENT_SCOPE",
4
  "message": "Token does not possess required scope 'write:plants' for action DELETE /v3/plant/100."
5
}

Security Best Practices