Authentication and ownership permissions
Understand when Conduit operations are public, authenticated, optionally authenticated, or restricted to an owner.
The API uses the operation's security declaration and the resource's ownership to decide whether a request can proceed. Read operations can be public or optionally personalized; mutations generally require Token; owner-only mutations additionally require that the authenticated user owns the resource.
Permission model
The diagram describes the observable boundaries in the contract and authorization suite. An operation without a security declaration is not automatically owner-authorized; inspect its description and resource behavior before deciding whether to send a token.
Permission categories
| Category | Request behavior | Examples in the contract |
|---|---|---|
| Public | No token is required. | GET /profiles/{username}, GET /articles, and GET /articles/{slug}. |
| Optional authentication | The request works without a token, but a valid token can personalize fields such as following or favorited. | Profile and global article reads are documented with optional authentication. |
| Authenticated | Send Authorization: Token <jwt>. A missing or unauthorized token produces 401. | GET /user, PUT /user, follow and unfollow, article feed, and mutations. |
| Owner-only | Send a valid token for the user who owns the resource. Another authenticated user receives 403 and the resource remains unchanged. | Updating or deleting another user's article and deleting another user's comment. |
Use the Token header
For a protected operation, send the exact header format:
~http Authorization: Token <jwt> ~
The token is returned by registration, login, and the current-user update response. See Authentication and token usage for the complete flow. Do not substitute Bearer for Token.
Handle authorization failures
Treat 401 and 403 as different conditions:
401means the request does not have an acceptable authentication context. Check that the header is present and usesToken <jwt>, then obtain a current token if needed.403means the request reached an ownership check but the authenticated user is not allowed to change that resource. Use the owning user's token or stop the mutation; do not retry the same request with the other user's token.
The authorization suite creates an article as user A, then verifies that user B receives 403 with errors.article[0] equal to forbidden for update and delete. It also verifies the same boundary for comment deletion with errors.comment[0] equal to forbidden, and confirms the comment remains after the rejected delete.
When implementing a backend, preserve the resource after a rejected owner-only mutation and return the documented error envelope. When building a frontend, use the response status and error key to explain whether the user must authenticate or lacks ownership. See Error envelope and HTTP status behavior for the common error shape and Backend conformance for the verification workflow.