Authentication¶

The Authentication API handles user registration, login, session management, and API key lifecycle. All endpoints are prefixed with /auth.

POST /auth/register¶

Create a new user account.


Auth required	No
Rate limit	5 requests / minute per IP

Request Body¶

Field	Type	Required	Description
`email`	string	Yes	Valid email address
`password`	string	Yes	Minimum 8 characters, must include uppercase, lowercase, and a digit
`full_name`	string	Yes	User's full name
`company`	string	No	Company or organization name

Example Request¶

curl -X POST https://app.meterbase.io/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "password": "SecurePass123",
    "full_name": "Jane Doe",
    "company": "Acme Properties"
  }'

Example Response¶

201 Created

{
  "id": "usr_a1b2c3d4",
  "email": "jane@example.com",
  "full_name": "Jane Doe",
  "company": "Acme Properties",
  "tier": "free",
  "created_at": "2026-03-25T14:00:00Z"
}

Error Cases¶

Status	Detail	Cause
`422`	`"field required"`	Missing required field
`422`	`"ensure this value has at least 8 characters"`	Password too short
`400`	`"Email already registered"`	Duplicate email address

POST /auth/login¶

Authenticate a user and obtain a JWT access token.


Auth required	No
Rate limit	10 requests / minute per IP

Request Body¶

The request uses application/x-www-form-urlencoded format (OAuth2 compatible).

Field	Type	Required	Description
`username`	string	Yes	The user's email address
`password`	string	Yes	The user's password

Example Request¶

curl -X POST https://app.meterbase.io/api/v1/auth/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=jane@example.com&password=SecurePass123"

Example Response¶

200 OK

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfYTFiMmMzZDQiLCJleHAiOjE3MTE0MDAwMDB9.SIGNATURE",
  "token_type": "bearer"
}

Token Lifetime

Access tokens expire after 24 hours. Your application should handle 401 responses by re-authenticating.

Error Cases¶

Status	Detail	Cause
`401`	`"Incorrect email or password"`	Invalid credentials
`422`	`"field required"`	Missing username or password

GET /auth/me¶

Retrieve the currently authenticated user's profile.


Auth required	Yes

Example Request¶

curl https://app.meterbase.io/api/v1/auth/me \
  -H "Authorization: Bearer $TOKEN"

Example Response¶

200 OK

{
  "id": "usr_a1b2c3d4",
  "email": "jane@example.com",
  "full_name": "Jane Doe",
  "company": "Acme Properties",
  "tier": "pro",
  "is_active": true,
  "created_at": "2026-01-15T10:30:00Z",
  "last_login": "2026-03-25T08:15:00Z"
}

Error Cases¶

Status	Detail	Cause
`401`	`"Not authenticated"`	Missing or expired token

GET /auth/api-keys¶

List all API keys for the authenticated user.


Auth required	Yes

Example Request¶

curl https://app.meterbase.io/api/v1/auth/api-keys \
  -H "Authorization: Bearer $TOKEN"

Example Response¶

200 OK

[
  {
    "id": "key_x1y2z3",
    "name": "Production Server",
    "prefix": "giq_prod_",
    "created_at": "2026-02-01T12:00:00Z",
    "last_used_at": "2026-03-25T07:45:00Z",
    "is_active": true
  },
  {
    "id": "key_a4b5c6",
    "name": "CI Pipeline",
    "prefix": "giq_ci_",
    "created_at": "2026-03-10T09:00:00Z",
    "last_used_at": null,
    "is_active": true
  }
]

Note

The full API key value is never returned after creation. Only the prefix is shown for identification purposes.

Error Cases¶

Status	Detail	Cause
`401`	`"Not authenticated"`	Missing or expired token

POST /auth/api-keys¶

Create a new API key. The full key is returned only once in the response.


Auth required	Yes

Request Body¶

Field	Type	Required	Description
`name`	string	Yes	A descriptive name for the key

Example Request¶

curl -X POST https://app.meterbase.io/api/v1/auth/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Server"
  }'

Example Response¶

201 Created

{
  "id": "key_x1y2z3",
  "name": "Production Server",
  "key": "giq_prod_sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "created_at": "2026-03-25T14:30:00Z"
}

Store the key securely

The key field is displayed only in this response. Copy it immediately and store it in a secrets manager. It cannot be retrieved later.

Using the API Key¶

Once created, include the key in the X-API-Key header:

curl https://app.meterbase.io/api/v1/auth/me \
  -H "X-API-Key: giq_prod_sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

Error Cases¶

Status	Detail	Cause
`401`	`"Not authenticated"`	Missing or expired token
`422`	`"field required"`	Missing `name` field
`400`	`"API key limit reached"`	Maximum number of keys per account exceeded