Authentication & Organizations

AgentWallie supports two authentication methods:

API Key (Authorization: Bearer sk_...) -- used for SDK and data-plane endpoints (events, config, products, etc.)
JWT Token (Authorization: Bearer eyJ...) -- used for management endpoints (auth, organizations, projects)

Most management endpoints listed here use JWT authentication. The token is obtained via signup or login.

Management endpoints (orgs, members, projects) support both API key and JWT auth. The auth routes (/v1/auth/*) are unauthenticated (signup, login) or JWT-authenticated (me, logout).

Sign Up

POST /v1/auth/signup

Creates a new user account. Automatically creates a default organization and an owner membership.

Request Body

Field	Type	Required	Description
`email`	string	Yes	Valid email address
`password`	string	Yes	Minimum 8 characters
`name`	string	No	Display name

Example

curl -X POST https://agentwallie.com/api/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@example.com",
    "password": "securepass123",
    "name": "Alice"
  }'

Response `201 Created`

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "usr_abc123",
    "email": "alice@example.com",
    "name": "Alice"
  },
  "organization": {
    "id": "org_def456",
    "name": "Alice's Org",
    "slug": "alice-1706000000000"
  }
}

⚠️

Returns 409 if the email is already registered. Use the login endpoint instead.

Login

POST /v1/auth/login

Request Body

Field	Type	Required	Description
`email`	string	Yes	Registered email address
`password`	string	Yes	Account password

Example

curl -X POST https://agentwallie.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@example.com",
    "password": "securepass123"
  }'

Response `200 OK`

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "usr_abc123",
    "email": "alice@example.com",
    "name": "Alice"
  }
}

Error `401`

{
  "error": "Invalid email or password.",
  "code": "INVALID_CREDENTIALS",
  "suggestion": "Check your email and password and try again."
}

Logout

POST /v1/auth/logout

Client-side logout acknowledgement. Since JWTs are stateless, the server does not invalidate the token -- the client should discard it.

Example

curl -X POST https://agentwallie.com/api/v1/auth/logout \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response `200 OK`

{
  "message": "Logged out"
}

Get Current User

GET /v1/auth/me

Returns the authenticated user's profile. Requires a valid JWT token.

Example

curl https://agentwallie.com/api/v1/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response `200 OK`

{
  "user": {
    "id": "usr_abc123",
    "email": "alice@example.com",
    "name": "Alice",
    "createdAt": "2025-01-15T10:00:00.000Z"
  }
}

Using JWT Tokens

Include the JWT token in the Authorization header for all authenticated requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

The token payload contains:

sub -- User ID
email -- User email
Standard JWT claims (iat, exp)

Organizations

Organizations group projects and team members. All org endpoints require JWT authentication.

List Organizations

GET /v1/orgs

Returns all organizations the authenticated user belongs to, with their role in each.

Example

curl https://agentwallie.com/api/v1/orgs \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response `200 OK`

[
  {
    "id": "org_def456",
    "name": "Alice's Org",
    "slug": "alice-1706000000000",
    "createdAt": "2025-01-15T10:00:00.000Z",
    "updatedAt": "2025-01-15T10:00:00.000Z",
    "role": "owner"
  }
]

Create Organization

POST /v1/orgs

Creates a new organization. The authenticated user becomes the owner.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Organization name
`slug`	string	Yes	URL-friendly slug (lowercase alphanumeric and hyphens only)

Example

curl -X POST https://agentwallie.com/api/v1/orgs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -d '{
    "name": "Acme Corp",
    "slug": "acme-corp"
  }'

Response `201 Created`

{
  "id": "org_ghi789",
  "name": "Acme Corp",
  "slug": "acme-corp",
  "createdAt": "2025-01-15T10:00:00.000Z",
  "updatedAt": "2025-01-15T10:00:00.000Z",
  "role": "owner"
}

⚠️

Returns 409 if the slug is already taken.

Get Organization Detail

GET /v1/orgs/:orgId

Returns organization details including member and project counts. Requires membership in the organization.

Example

curl https://agentwallie.com/api/v1/orgs/org_def456 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response `200 OK`

{
  "id": "org_def456",
  "name": "Alice's Org",
  "slug": "alice-1706000000000",
  "createdAt": "2025-01-15T10:00:00.000Z",
  "updatedAt": "2025-01-15T10:00:00.000Z",
  "role": "owner",
  "_count": {
    "members": 3,
    "projects": 2
  }
}

List Members

GET /v1/orgs/:orgId/members

Example

curl https://agentwallie.com/api/v1/orgs/org_def456/members \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response `200 OK`

[
  {
    "id": "mem_001",
    "role": "owner",
    "createdAt": "2025-01-15T10:00:00.000Z",
    "user": {
      "id": "usr_abc123",
      "email": "alice@example.com",
      "name": "Alice"
    }
  },
  {
    "id": "mem_002",
    "role": "member",
    "createdAt": "2025-01-16T08:30:00.000Z",
    "user": {
      "id": "usr_xyz789",
      "email": "bob@example.com",
      "name": "Bob"
    }
  }
]

Invite Member

POST /v1/orgs/:orgId/members

Adds an existing user to the organization. Only owners and admins can invite members.

The invitee must already have an AgentWallie account. If not, they need to sign up first.

Request Body

Field	Type	Required	Description
`email`	string	Yes	Email of the user to invite
`role`	string	No	`"member"` (default) or `"admin"`

Example

curl -X POST https://agentwallie.com/api/v1/orgs/org_def456/members \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -d '{
    "email": "bob@example.com",
    "role": "admin"
  }'

Response `201 Created`

{
  "id": "mem_003",
  "role": "admin",
  "createdAt": "2025-01-16T08:30:00.000Z",
  "user": {
    "id": "usr_xyz789",
    "email": "bob@example.com",
    "name": "Bob"
  }
}

Errors

Status	Code	Description
`403`	`FORBIDDEN`	Caller is not an owner or admin
`404`	`USER_NOT_FOUND`	No account with that email
`409`	`ALREADY_MEMBER`	User is already in the organization

Remove Member

DELETE /v1/orgs/:orgId/members/:memberId

Removes a member from the organization. Only owners and admins can remove members. Owners cannot remove themselves.

Example

curl -X DELETE https://agentwallie.com/api/v1/orgs/org_def456/members/mem_002 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response `200 OK`

{
  "message": "Member removed"
}

List Organization Projects

GET /v1/orgs/:orgId/projects

Returns all projects within the organization.

Example

curl https://agentwallie.com/api/v1/orgs/org_def456/projects \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response `200 OK`

[
  {
    "id": "proj_abc123",
    "name": "My App",
    "organizationId": "org_def456",
    "createdAt": "2025-01-15T10:00:00.000Z",
    "updatedAt": "2025-01-15T10:00:00.000Z"
  }
]

Create Project in Organization

POST /v1/orgs/:orgId/projects

Creates a new project within the organization. Automatically generates public and private API keys.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Project name

Example

curl -X POST https://agentwallie.com/api/v1/orgs/org_def456/projects \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -d '{
    "name": "My New App"
  }'

Response `201 Created`

{
  "id": "proj_xyz789",
  "name": "My New App",
  "organizationId": "org_def456",
  "publicKey": "pk_live_abc...",
  "privateKey": "sk_live_xyz...",
  "createdAt": "2025-01-15T10:00:00.000Z",
  "updatedAt": "2025-01-15T10:00:00.000Z"
}

⚠️

The private key (sk_...) is only shown once at creation time. Store it securely.

Roles

Role	Permissions
`owner`	Full access. Can invite/remove members, manage projects, delete the org. Cannot remove themselves.
`admin`	Can invite/remove members, manage projects.
`member`	Read access to org resources.

Overview Projects

Authentication & Organizations

Sign Up

Request Body

Example

Response 201 Created

Login

Request Body

Example

Response 200 OK

Error 401

Logout

Example

Response 200 OK

Get Current User

Example

Response 200 OK

Using JWT Tokens

Organizations

List Organizations

Example

Response 200 OK

Create Organization

Request Body

Example

Response 201 Created

Get Organization Detail

Example

Response 200 OK

List Members

Example

Response 200 OK

Invite Member

Request Body

Example

Response 201 Created

Errors

Remove Member

Example

Response 200 OK

List Organization Projects

Example

Response 200 OK

Create Project in Organization

Request Body

Example

Response 201 Created

Roles

Response `201 Created`

Response `200 OK`

Error `401`

Response `200 OK`

Response `200 OK`

Response `200 OK`

Response `201 Created`

Response `200 OK`

Response `200 OK`

Response `201 Created`

Response `200 OK`

Response `200 OK`

Response `201 Created`