Saloon
GithubOfficial BookSponsor
v3
v3
  • 🀠Saloon
  • Upgrade
    • πŸͺ„What's new in v3
    • 🌳Upgrading from v2
  • The Basics
    • ⬇️Installation
    • πŸ”ŒConnectors
    • βœ‰οΈRequests
    • πŸ”Authentication
    • 🎁Sending Body/Data
      • JSON Body
      • Multipart Form Body
      • XML Body
      • URL Encoded Body (Form)
      • String / Plain Text Body
      • Stream Body
    • πŸš€Sending Requests
    • πŸ“‘Responses
    • πŸ”₯Handling Failures
    • πŸ”ŽDebugging
    • βœ…Testing
  • Digging Deeper
    • πŸ›ΈData Transfer Objects
    • ✨Building SDKs
    • ☝️Solo Requests
    • 🎯Retrying Requests
    • ⏸️Delaying Requests
    • 🏎️Concurrency & Pools
    • πŸ”‘OAuth2
      • Authorization Code Grant
      • Client Credentials Grant
    • πŸ’«Middleware
    • ⛩️PSR Support
  • Installable Plugins
    • πŸ“šPagination
      • Paged Pagination
      • Limit/Offset Pagination
      • Cursor Pagination
      • Custom Pagination
    • β›΅Laravel Plugin
    • πŸ”Caching
    • β›”Rate Limit Handler
    • 🏭Auto SDK Generator
    • 🀠Lawman
    • πŸ‡XML Wrangler
    • πŸ—οΈBuilding Your Own Plugins
  • Conclusion
    • πŸ“˜Official Book!
    • πŸ“”How-to Guides
      • Improving Speed With Laravel
      • Per-request Authentication
    • πŸ“–Tutorials & Blog Posts
    • πŸŽ–οΈShowcase
    • πŸ’₯Known Issues
    • πŸ€—Credits
    • ❀️Support Saloon
Powered by GitBook
On this page
  • Authorization "Bearer" Tokens
  • Basic Auth (Base64 Encoded)
  • Query Parameter
  • Certificate Auth
  • Header Auth
  • Multiple Authenticators
  • Custom Authentication
  • The authenticate method
Edit on GitHub
  1. The Basics

Authentication

PreviousRequestsNextSending Body/Data

Last updated 1 year ago

Saloon has optional authenticator classes to help you with the most common types of authentication. These are classes that can be used on your connector or request.

Authorization "Bearer" Tokens

The TokenAuthenticator class can be used to add a Authorization: Bearer header to the request. Just extend the defaultAuth method and return the authenticator class.

<?php

use Saloon\Http\Auth\TokenAuthenticator;

class ForgeConnector extends Connector
{
    public function __construct(public readonly string $token) {}
    
    protected function defaultAuth(): TokenAuthenticator
    {
        return new TokenAuthenticator($this->token);
    }
}

Basic Auth (Base64 Encoded)

The BasicAuthenticator class can be used to add a Authorization: Basic header to the request. Just extend the defaultAuth method and return the authenticator class.

<?php

use Saloon\Http\Auth\BasicAuthenticator;

class ForgeConnector extends Connector
{
    public function __construct(
        public readonly string $username,
        public readonly string $password
    ){}
    
    protected function defaultAuth(): BasicAuthenticator
    {
        return new BasicAuthenticator($this->username, $this->password);
    }
}

Query Parameter

The QueryAuthenticator class can be used to add a query parameter to requests. Just extend the defaultAuth method and return the authenticator class.

<?php

use Saloon\Http\Auth\QueryAuthenticator;

class ForgeConnector extends Connector
{
    public function __construct(public readonly string $token) {}
    
    protected function defaultAuth(): QueryAuthenticator
    {
        return new QueryAuthenticator('api-key', $this->token);
    }
}

Certificate Auth

The CertificateAuthenticator class can be used to authenticate with a custom client-side certificate. An optional password can be provided. Just extend the defaultAuth method and return the authenticator class.

<?php

use Saloon\Http\Auth\CertificateAuthenticator;

class ForgeConnector extends Connector
{
    public function __construct(
        public readonly string $path,
        public readonly string $password
    ){}
    
    protected function defaultAuth(): CertificateAuthenticator
    {
        return new CertificateAuthenticator($this->path, $this->password);
    }
}

Header Auth

The HeaderAuthenticator class can be used to authenticate with a custom header. Just extend the defaultAuth method and return the authenticator class.

<?php

use Saloon\Http\Auth\HeaderAuthenticator;

class ForgeConnector extends Connector
{
    public function __construct(public readonly string $token) {}
    
    protected function defaultAuth(): HeaderAuthenticator
    {
        return new HeaderAuthenticator($this->token, 'X-API-KEY');
    }
}

Multiple Authenticators

You may need to use multiple authenticator classes together, like a certificate and an authorization token. You can use the MultiAuthenticator class for this scenario.

<?php

use Saloon\Http\Auth\MultiAuthenticator;
use Saloon\Http\Auth\TokenAuthenticator;
use Saloon\Http\Auth\CertificateAuthenticator;

class ForgeConnector extends Connector
{
    public function __construct(
        public readonly string $certificate,
        public readonly string $token
    ){}
    
    protected function defaultAuth(): MultiAuthenticator
    {
        return new MultiAuthenticator(
            new CertificateAuthenticator($this->certificate),
            new TokenAuthenticator($this->token),
        );
    }
}

Custom Authentication

If your API integration requires a more complicated authentication process, you can create your own authenticator classes which can be used on your connector. This helps abstract any complicated logic away from the connector keeping it tidy.

<?php

use Saloon\Http\PendingRequest;
use Saloon\Contracts\Authenticator;

class ForgeAuthenticator implements Authenticator
{
    public function __construct(public readonly string $token) {}

    public function set(PendingRequest $pendingRequest): void
    {
        // $pendingRequest->headers()->add(...);
        // $pendingRequest->config()->add(...);
    }
}
<?php

class ForgeConnector extends Connector
{
    protected function defaultAuth(): ForgeAuthenticator
    {
        return new ForgeAuthenticator($this->token);
    }
}

The authenticate method

You may also use the authenticate method on your connector or request if you would like to use or overwrite an authenticator at runtime.

$forge = new ForgeConnector;

$forge->authenticate(new TokenAuthenticator($user->forge_token));

// $forge->send(...)

Only one authenticator can be used at the same time.

πŸ”
You can view all of the built-in authenticators on GitHub.