Authentication

StyleGrab uses JWT tokens and API keys for authentication.

Authentication Methods

API Keys (Recommended)

API keys are the preferred method for programmatic access:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.stylegrab.dev/api/extractions

JWT Tokens

Used by the web dashboard. Obtained via login:

curl -X POST https://api.stylegrab.dev/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'

Endpoints

Register

Create a new account.

POST /api/auth/register

Request Body:

{
  "email": "you@example.com",
  "password": "min-8-characters",
  "name": "Your Name"
}

Response:

{
  "id": "user_abc123",
  "email": "you@example.com",
  "name": "Your Name",
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

Login

Authenticate and receive a JWT token.

POST /api/auth/login

Request Body:

{
  "email": "you@example.com",
  "password": "your-password"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": "2024-01-22T10:30:00Z"
}

Get Current User

Retrieve the authenticated user’s profile.

GET /api/auth/me

Headers:

Authorization: Bearer YOUR_TOKEN

Response:

{
  "id": "user_abc123",
  "email": "you@example.com",
  "name": "Your Name",
  "created_at": "2024-01-15T10:30:00Z"
}

Create API Key

Generate a new API key for programmatic access.

POST /api/auth/api-keys

Request Body:

{
  "name": "CI Pipeline Key",
  "expires_at": "2025-01-15T00:00:00Z"
}

Response:

{
  "id": "key_abc123",
  "name": "CI Pipeline Key",
  "key": "sg_live_abc123xyz...",
  "expires_at": "2025-01-15T00:00:00Z",
  "created_at": "2024-01-15T10:30:00Z"
}

⚠️ Important: The key is only shown once. Store it securely.

Revoke API Key

Delete an API key.

DELETE /api/auth/api-keys/:id

Response:

{
  "success": true
}

Error Responses

Example error response:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or expired token"
  }
}

Best Practices

1. Use API keys for server-to-server communication
2. Set expiration dates on API keys
3. Rotate keys regularly and revoke unused ones
4. Never commit keys to version control
5. Use environment variables to store keys