✎ Edit on GitHub


The auth property on Request let's you authenticate users and also provides some convenience methods for accessing common authorization headers.


The authorization header is a great place to send credentials from a client.

Authorization: xxxxxxxxxx

You can access the authorization header through req.auth.header. Two common patterns are basic and bearer.


Basic authorization consists of a username and password concatenated into a string and base64 encoded.

Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l

This is what an example header looks like. You can read more about basic auth on wikipedia.

Below is how you access this header using req.auth.

guard let credentials = req.auth.header?.basic else {
    throw Abort.badRequest

The basic header returns an APIKey credential.

class APIKey: Credentials {
    let id: String
    let secret: String


Another common method is bearer which consists of a single API key.

Authorization: Bearer apikey123

It is accessed similarly to the basic header and returns an AccessToken credential.

class AccessToken: Credentials {
    let string: String


To access the raw authorization header, use req.auth.header?.header.


Both Basic and Bearer return something that conforms to Credentials. You can always create a custom Credentials object for authentication by conforming your own class to Credentials or by manually creating an APIKey, AccessToken, or Identifier.

let key = AccessToken(string: "apikey123")


You can also create credentials from form or JSON data.

    let username = req.data["username"]?.string,
    let password = req.data["password"]?.string
else {
    throw Abort.badRequest

let key = APIKey(id: username, secret: password)


Once you have some object that conforms to Credentials, you can try to login the user.

try req.auth.login(credentials)

If this call succeeds, the user is logged in and a session has been started. They will stay logged in as long as their cookie is valid.


Logging in calls the authenticate method on Auth.User model you supplied to the AuthMiddleware. Make sure you add support for all the credential types you may want to use.

Note: If you used a custom Realm, it will be called instead.


Another important credential type is the Identifier type. This is used by Vapor when fetching the User object from the vapor-auth cookie. It is also a convenient way to log a user in manually.

static func authenticate(credentials: Credentials) throws -> Auth.User {
    switch credentials {
    case let id as Identifier:
        guard let user = try User.find(id.id) else {
            throw Abort.custom(status: .badRequest, message: "Invalid identifier.")

        return user

Adding the Identifier case for Credentials is easy, just look up the user by the identifier.

let id = Identifier(id: 42)
try req.auth.login(id)

Now you can manually log users in with just their identifiers.


If you just want to log the user in for a single request, disable persistance.

req.auth.login(credentials, persist: false)

Note: Supporting Identifier credentials is required for persisted authentication to work properly.


By default, request.auth.user() returns the authorized Auth.User. This will need to be casted to your internal User type for use.

Adding a convenience method on Request is a great way to simplify this.

extension Request {
    func user() throws -> User {
        guard let user = try auth.user() as? User else {
            throw Abort.custom(status: .badRequest, message: "Invalid user type.")

        return user

Now you can access your User type with try req.user().