SemaiSens API Authentication: API Keys and Bearer Tokens

Generate and manage API keys in your SemaiSens dashboard, then authenticate every API request using a Bearer token in the Authorization header.

Every request to the SemaiSens API must be authenticated using an API key. You generate and manage API keys directly in your account dashboard — no OAuth flow or client credentials are required. Once you have a key, include it as a Bearer token in the Authorization header of every request.

Getting Your API Key

1. Log in to your dashboard

   Go to app.example.com and sign in with your SemaiSens account credentials.

2. Open API Key settings

   Navigate to Settings → API Keys in the left-hand navigation menu.

3. Create a new key

   Click New API Key. Select the appropriate scope (see Key Scopes below) and give the key a descriptive name such as Production Integration or CI Pipeline.

4. Copy the key immediately

   Your API key is displayed once at creation time. Copy it now and store it somewhere secure — the dashboard will never show the full key again. If you lose it, you must generate a new one.

Using Your API Key

Pass your API key in the Authorization header as a Bearer token on every request.

curl

curl https://api.example.com/v1/fields \
  -H "Authorization: Bearer YOUR_API_KEY"

Never hard-code your API key in source code or commit it to a version control repository. Use environment variables (e.g., SEMAISENS_API_KEY) or a secrets manager to inject the key at runtime. Anyone who obtains your key can make requests on your behalf.

Key Scopes

When creating a key, you assign it one of two scopes. Choose the most restrictive scope that satisfies your use case.

Scope	Permitted Operations	Recommended For
Read Only	GET requests only — list and retrieve resources	Dashboards, read-only reporting tools, third-party integrations that only need to display data
Read/Write	All operations — GET, POST, PATCH, DELETE	Backend services that create fields, upload imagery, trigger reports, or manage webhooks

Use separate API keys for different environments (development, staging, production) so you can rotate or revoke keys independently without affecting other environments.

Rotating Keys

To rotate a key, click Regenerate next to it in Settings → API Keys. The old key is invalidated immediately — requests using the old key will receive a 401 Unauthorized response. Update all integrations with the new key before triggering a rotation to avoid downtime.

If you suspect a key has been compromised, delete it immediately from the dashboard rather than rotating it. Deletion prevents any further use of that key.

Authentication Error Responses

Status	Cause	Resolution
401 Unauthorized	The Authorization header is missing, malformed, or the key is invalid or deleted.	Verify the header format is Bearer YOUR_API_KEY and that the key exists in your dashboard.
403 Forbidden	The key is valid but its scope does not permit the requested operation (e.g., a Read Only key attempting a POST).	Generate a Read/Write key or adjust the scope of the existing key.