🔐

Authentication

There are several ways to authenticate with an API; most of the time, you are expected to provide a header or query parameter to authenticate. Saloon has built helpers for the most common authentication methods to help you, but you can also create custom authenticators for advanced authentication. You can also provide defaults for authentication should you require it.
While you may opt-in to Saloon's authentication classes, it's not the only way to authenticate. Another good method of authentication is using the defaultHeaders, defaultConfig or defaultQuery on your connector/request.
Available Authentication Methods
These authentication methods are available on both the connector and the request instances.
1.withTokenAuth($token, $prefix = 'Bearer')
Sends an Authorization header e.g Authorization: Bearer your-api-key
2.withBasicAuth($username, $password)
Uses HTTP "basic" authentication
3.withDigestAuth($username, $password)
Uses HTTP "basic" authentication with a digest
4.withQueryAuth($parameter, $value)
Uses a query parameter to authenticate. e.g ?api_key=your-api-key
Authenticating all requests
Most of the time, you use one API key for all your API requests to a service, like a personal access token or a username/password combination. Therefore, it's recommended that you use the constructor of your connector and expect an API token to be provided. This is useful if you have a different API key per user that needs to be passed into your connector.
Definition
Usage
<?php
​
class ForgeConnector extends Connector
{ 
    public function resolveBaseUrl(): string
    {
        return 'https://forge.laravel.com/api/v1';
    }
​
    /**
     * Constructor
     *
     * @param string $apiKey
     */
    public function __construct(protected string $apiKey)
    {
        $this->withTokenAuth($this->apiKey);
    }
}
<?php
​
$forge = new ForgeConnector('my-api-key');
​
// All API requests will be authenticated with the API key
Default authentication
Sometimes you may use a single API key in your .env file/application config, and you don't want to pass it in every time you instantiate; you may use the defaultAuth method on your connector, and every request will be authenticated.
Definition
Usage
<?php
​
use Saloon\Contracts\Authenticator;
use Saloon\Http\Auth\TokenAuthenticator;
​
class ForgeConnector extends Connector
{ 
    public function resolveBaseUrl(): string
    {
        return 'https://forge.laravel.com/api/v1';
    }
​
    protected function defaultAuth(): ?Authenticator
    {
        return new TokenAuthenticator(config('app.services.forge'));
    }
}
<?php
​
$forge = new ForgeConnector;
​
// All API requests will be authenticated with the default auth.
Authenticator Classes
Method
Class
withTokenAuth
use Saloon\Http\Auth\TokenAuthenticator;
withBasicAuth
use Saloon\Http\Auth\BasicAuthenticator;
withDigestAuth
use Saloon\Http\Auth\DigestAuthenticator;
withQueryAuth
use Saloon\Http\Auth\QueryAuthenticator;
Authentication on the fly
You may want to authenticate a request or a connector on the fly on a per-request or per-connector basis. You can use the authentication methods directly.
Connector
Request
<?php
​
$forge = new ForgeConnector;
$forge->withTokenAuth($user->forge_api_key);
​
// All API requests sent with this connector instance will be authenticated.
<?php
​
$request = new GetServersRequest;
$request->withTokenAuth($user->forge_api_key);
​
// This single request sent will be authenticated.
Custom Authenticators
Sometimes the API integration you are building requires multiple ways to authenticate, like a token and a certificate or perhaps authenticating an OAuth 2 API. When the built-in authentication is insufficient, You can build custom authenticators that can be transported between your application and Saloon's requests.
Definition
Usage (Connector)
Usage (Request)
<?php
​
use Saloon\Contracts\PendingRequest;
use Saloon\Contracts\Authenticator;
​
class CustomAuthenticator implements Authenticator
{
    public function __construct(
        public string $apiKey,
    ) {
        //
    }
​
    public function set(PendingRequest $pendingRequest): void
    {
        $pendingRequest->headers()->add('X-API-Key', $this->apiKey);
    }
}
<?php
​
$forge = new ForgeConnector;
$forge->authenticate(new CustomAuthenticator('my-api-key'));
​
// When requests are sent with this connector, the X-API-KEY header is added.
​
<?php
​
$request = new GetServersRequest;
$request->authenticate(new CustomAuthenticator('my-api-key'));
​
// When the request is sent with this connector, the X-API-KEY header is added.
You may use custom authenticators in the same way as other authenticators, so you may use the defaultAuth method or even authenticate on the fly.

Method	Class
withTokenAuth	use Saloon\Http\Auth\TokenAuthenticator;
withBasicAuth	use Saloon\Http\Auth\BasicAuthenticator;
withDigestAuth	use Saloon\Http\Auth\DigestAuthenticator;
withQueryAuth	use Saloon\Http\Auth\QueryAuthenticator;

The Basics - Previous

Request Body/Data

Next - The Basics

Sending Requests

Last modified 3d ago