AutoCom Docs

Authorization API

This page documents all authentication and authorization endpoints in AutoCom.

Authentication Endpoints

Register Tenant

Create a new tenant with an owner account.

POST /api/v1/tenants

Request Body:

Field Type Required Description
company_name string Yes Organization name
domain string Yes Unique tenant identifier (alphanumeric, dashes)
admin_name string Yes Owner's full name
admin_email string Yes Owner's email address
admin_password string Yes Password (min 8 characters)
admin_password_confirmation string Yes Password confirmation

Example:

curl -X POST https://api.autocom.example/api/v1/tenants \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "My Store",
    "domain": "my-store",
    "admin_name": "John Doe",
    "admin_email": "john@mystore.com",
    "admin_password": "securepass123",
    "admin_password_confirmation": "securepass123"
  }'

Response (201 Created):

{
  "message": "Tenant registered successfully",
  "tenant": {
    "id": "my-store",
    "name": "My Store",
    "domain": "my-store"
  },
  "user": {
    "id": 1,
    "name": "John Doe",
    "email": "john@mystore.com",
    "role": "owner"
  },
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
  "token_type": "Bearer"
}

Login

Authenticate a user within a tenant context.

POST /api/v1/auth/login
X-Tenant: {tenant-id}

Request Body:

Field Type Required Description
email string Yes User's email
password string Yes User's password

Example:

curl -X POST https://api.autocom.example/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -H "X-Tenant: my-store" \
  -d '{
    "email": "john@mystore.com",
    "password": "securepass123"
  }'

Response (200 OK):

{
  "message": "Login successful",
  "user": {
    "id": 1,
    "name": "John Doe",
    "email": "john@mystore.com",
    "role": "owner",
    "permissions": [
      "dashboard.view",
      "dashboard.view_analytics",
      "orders.view",
      "orders.create",
      ...
    ]
  },
  "tenant": {
    "id": "my-store",
    "name": "My Store"
  },
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
  "token_type": "Bearer"
}

Error Responses:

Status Condition
400 Missing X-Tenant header
401 Invalid credentials
403 Account inactive or suspended
404 Tenant not found

Logout

Revoke the current access token.

POST /api/v1/auth/logout
Authorization: Bearer {token}
X-Tenant: {tenant-id}

Response (200 OK):

{
  "message": "Successfully logged out"
}

Get Current User

Retrieve the authenticated user's profile and permissions.

GET /api/v1/auth/me
Authorization: Bearer {token}
X-Tenant: {tenant-id}

Response (200 OK):

{
  "id": 1,
  "name": "John Doe",
  "email": "john@mystore.com",
  "email_verified": true,
  "is_super_admin": false,
  "created_at": "2024-01-01T00:00:00Z",
  "last_login_at": "2024-01-07T15:30:00Z",
  "tenant_membership": {
    "role": "owner",
    "status": "active",
    "joined_at": "2024-01-01T00:00:00Z",
    "permissions": ["dashboard.view", ...]
  },
  "tenants": [
    {
      "id": "my-store",
      "name": "My Store",
      "role": "owner",
      "is_current": true
    },
    {
      "id": "other-store",
      "name": "Other Store",
      "role": "agent",
      "is_current": false
    }
  ]
}

List User's Tenants

Get all organizations the user belongs to.

GET /api/v1/auth/tenants
Authorization: Bearer {token}

Response (200 OK):

{
  "tenants": [
    {
      "id": "my-store",
      "name": "My Store",
      "role": "owner",
      "joined_at": "2024-01-01T00:00:00Z"
    },
    {
      "id": "other-store",
      "name": "Other Store",
      "role": "agent",
      "joined_at": "2024-01-05T10:00:00Z"
    }
  ]
}

Change Password

Update the authenticated user's password.

POST /api/v1/auth/change-password
Authorization: Bearer {token}

Request Body:

Field Type Required Description
current_password string Yes Current password
password string Yes New password (min 8 chars)
password_confirmation string Yes Confirm new password

Response (200 OK):

{
  "message": "Password changed successfully"
}

Team Management Endpoints

List Team Members

GET /api/v1/team
Authorization: Bearer {token}
X-Tenant: {tenant-id}

Required Permission: team.view

Invite Team Member

POST /api/v1/team/invite
Authorization: Bearer {token}
X-Tenant: {tenant-id}

Required Permission: team.invite

Request Body:

Field Type Required Description
email string Yes Invitee's email
role_id integer Yes Role to assign

Accept Invitation

POST /api/v1/invitations/accept

No authentication required.

Request Body:

Field Type Required Description
token string Yes Invitation token
name string New users User's name
password string New users Password
password_confirmation string New users Confirm password

List Pending Invitations

GET /api/v1/team/invitations
Authorization: Bearer {token}
X-Tenant: {tenant-id}

Required Permission: team.invite

Resend Invitation

POST /api/v1/team/invitations/{id}/resend
Authorization: Bearer {token}
X-Tenant: {tenant-id}

Required Permission: team.invite

Cancel Invitation

DELETE /api/v1/team/invitations/{id}
Authorization: Bearer {token}
X-Tenant: {tenant-id}

Required Permission: team.invite

Update Member Role

PATCH /api/v1/team/members/{id}/role
Authorization: Bearer {token}
X-Tenant: {tenant-id}

Required Permission: team.manage_roles

Request Body:

Field Type Required Description
role_id integer Yes New role ID

Suspend Member

POST /api/v1/team/members/{id}/suspend
Authorization: Bearer {token}
X-Tenant: {tenant-id}

Required Permission: team.remove

Reactivate Member

POST /api/v1/team/members/{id}/reactivate
Authorization: Bearer {token}
X-Tenant: {tenant-id}

Required Permission: team.edit

Remove Member

DELETE /api/v1/team/members/{id}
Authorization: Bearer {token}
X-Tenant: {tenant-id}

Required Permission: team.remove

Role & Permission Endpoints

List Available Roles

GET /api/v1/team/roles
Authorization: Bearer {token}
X-Tenant: {tenant-id}

Required Permission: team.view

Get Role Details

GET /api/v1/team/roles/{id}
Authorization: Bearer {token}
X-Tenant: {tenant-id}

Required Permission: team.view

List All Permissions

GET /api/v1/team/permissions
Authorization: Bearer {token}
X-Tenant: {tenant-id}

Required Permission: team.manage_roles

Error Responses

Authentication Errors

{
  "message": "Unauthenticated"
}

Status: 401

Authorization Errors

{
  "message": "You do not have permission to perform this action",
  "required_permission": "team.invite"
}

Status: 403

Tenant Membership Errors

{
  "message": "You are not a member of this organization"
}

Status: 403

{
  "message": "Your access to this organization has been suspended",
  "status": "suspended"
}

Status: 403

Validation Errors

{
  "message": "The given data was invalid",
  "errors": {
    "email": ["The email field is required."],
    "role_id": ["The selected role is invalid."]
  }
}

Status: 422

Request Headers Summary

Header Required Description
Authorization For protected routes Bearer token from login
X-Tenant For tenant-scoped routes Tenant identifier
Content-Type For POST/PATCH/PUT application/json
Accept Recommended application/json

Rate Limiting

Endpoint Limit
Login 5 requests/minute per IP
Register 3 requests/minute per IP
All other endpoints 60 requests/minute per user

Rate limit headers are included in responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1704672000