Configuration

How configuration is read

The service provider merges the package's config/adobe-sign.php under the adobe-sign key, so config('adobe-sign.signature_level') works whether or not you published the file. Values that change between environments (keys, secrets, levels, cache store) read .env; structural values (route paths, middleware, retry counts) are plain config.

AdobeSignManager receives the whole adobe-sign array when it is built. It is bound scoped, which means one instance per HTTP request, per Octane request and per queued job. Two consequences follow:

• After php artisan config:cache, editing .env has no effect until you cache again. This is standard Laravel behaviour, but it is the most common reason a new key "doesn't work".
• If you change config at runtime with config([...]), an already-built manager keeps the old values for the rest of that request. Change config before the first call, or see Changing values at runtime.

The routes are registered from config at boot, so oauth.* route settings and webhooks.enabled/path/middleware must be set in the config file (or .env), not at runtime.

The .env variables at a glance

# Authentication
ADOBE_SIGN_AUTH=integration_key          # or oauth
ADOBE_SIGN_INTEGRATION_KEY=

# OAuth application
ADOBE_SIGN_CLIENT_ID=
ADOBE_SIGN_CLIENT_SECRET=
ADOBE_SIGN_REDIRECT_URI=                 # defaults to route('adobe-sign.oauth.callback')
ADOBE_SIGN_SCOPES="user_login:self agreement_read:self agreement_write:self agreement_send:self webhook_read:self webhook_write:self"

# Signature level
ADOBE_SIGN_SIGNATURE_LEVEL=ses           # ses, aes or qes
ADOBE_SIGN_QUALIFIED_ISSUERS=            # comma-separated certificate issuers

# Infrastructure
ADOBE_SIGN_BOOTSTRAP_URL=https://api.adobesign.com
ADOBE_SIGN_CACHE_STORE=                  # empty = default cache store
ADOBE_SIGN_LOG_CHANNEL=                  # empty = default channel, false = off

# Webhooks
ADOBE_SIGN_WEBHOOK_CLIENT_IDS=           # comma-separated; empty = ADOBE_SIGN_CLIENT_ID

Authentication

auth only decides what the default client is. AdobeSign::forUser($user) always uses OAuth, whatever auth says, so an app can send from its own account by default and from a user's account where it matters.

OAuth application and routes

Example: connect from a settings page behind your own guard, and land back on it.

'oauth' => [
    // ...
    'route_prefix' => 'settings/integrations/acrobat-sign',
    'route_middleware' => ['web', 'auth', 'verified'],
    'redirect_after' => '/settings/integrations?connected=acrobat-sign',
],

Request broader scopes only when you need them. agreement_read:account, for example, lets an account admin's token read every agreement in the account, and Adobe shows the user exactly what they are granting. The OAuth page covers scope choice.

Signature level

ADOBE_SIGN_SIGNATURE_LEVEL=qes
ADOBE_SIGN_QUALIFIED_ISSUERS="DigiCert,TrustPro QTSP"

The level becomes ClientOptions::$defaultSignatureLevel on every client the manager builds, including forUser() clients. It applies only to agreements passed to agreements()->create() as an AgreementInfo builder; a raw array or a generated model is sent as-is. The Signature levels page explains the levels and per-signer overrides.

Data centres, cache and retries

Why the cache matters: Acrobat Sign accounts live on shards (na1, na4, eu1, …) and every call must go to the right one. Without a shared cache, every PHP process would repeat the /baseUris lookup. With the default cache store it happens once per day for the whole app.

Why the retry ceiling matters: retries happen inside the request that made the call. In a web request, sleeping for a minute is worse than failing, so you may want a lower max_delay_seconds for web traffic and to let queued jobs handle RateLimitException with release(), as the download job in the walkthrough does. Without a Retry-After header the SDK backs off exponentially from one second.

Logging

The core logs requests and throttling retries. It never passes headers or bodies to the logger, so keys, tokens and document content stay out of your logs. Laravel's env() turns the string false into a boolean, so ADOBE_SIGN_LOG_CHANNEL=false turns logging off. A dedicated channel keeps the noise out of your main log:

'channels' => [
    // ...
    'adobe-sign' => [
        'driver' => 'daily',
        'path' => storage_path('logs/adobe-sign.log'),
        'level' => 'info',
        'days' => 14,
    ],
],

ADOBE_SIGN_LOG_CHANNEL=adobe-sign

The webhook controller logs rejected and unreadable deliveries through Laravel's default logger (the Log facade), not this channel.

Webhooks

You can add middleware to the webhook route as long as it doesn't need a session, a CSRF token or a logged-in user, and is fast; Adobe allows 5 seconds for the whole answer. A rate limiter or an IP allow-list is fine:

'webhooks' => [
    // ...
    'middleware' => ['throttle:120,1'],
],

The Webhooks page explains the handshake, dedupe and listeners in depth.

Examples per environment

Local development

ADOBE_SIGN_INTEGRATION_KEY=3AAABLblqZhB...developer-account-key...
ADOBE_SIGN_CACHE_STORE=file
ADOBE_SIGN_LOG_CHANNEL=stack
APP_URL=https://warm-otter-42.example-tunnel.dev   # your tunnel, so route('adobe-sign.webhook') is public HTTPS
ADOBE_SIGN_WEBHOOK_CLIENT_IDS=CBJCHBCAABAAdevapp

Production on several servers

ADOBE_SIGN_AUTH=integration_key
ADOBE_SIGN_INTEGRATION_KEY=${SECRET_FROM_YOUR_VAULT}
ADOBE_SIGN_SIGNATURE_LEVEL=aes
ADOBE_SIGN_CACHE_STORE=redis
ADOBE_SIGN_LOG_CHANNEL=adobe-sign
ADOBE_SIGN_WEBHOOK_CLIENT_IDS=CBJCHBCAABAAprodapp

A SaaS where customers connect their own accounts

ADOBE_SIGN_AUTH=oauth
ADOBE_SIGN_CLIENT_ID=CBJCHBCAABAAsaasapp
ADOBE_SIGN_CLIENT_SECRET=${SECRET_FROM_YOUR_VAULT}
ADOBE_SIGN_REDIRECT_URI=https://app.example.com/adobe-sign/oauth/callback
ADOBE_SIGN_CACHE_STORE=redis
# webhook allow-list falls back to ADOBE_SIGN_CLIENT_ID

Changing values at runtime

Because the manager reads config once per scope, a runtime change needs a fresh manager. In tests this is common:

config(['adobe-sign.signature_level' => 'qes']);
$this->app->forgetScopedInstances();                       // next resolve builds a new manager
\Conceptlz\AdobeSign\Laravel\Facades\AdobeSign::clearResolvedInstance(); // and the facade forgets the old one

For per-tenant credentials in production, don't rewrite global config. Build a core client for the tenant with Laravel services passed by name. Laravel's cache repository implements PSR-16 and its logger implements PSR-3, so they plug straight in:

use Conceptlz\AdobeSign\AdobeSign;
use Conceptlz\AdobeSign\ClientOptions;
use Conceptlz\AdobeSign\Enum\SignatureLevel;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Log;

final class TenantAdobeSign
{
    public static function for(Tenant $tenant): AdobeSign
    {
        return AdobeSign::withIntegrationKey(
            $tenant->adobe_sign_integration_key,   // e.g. an encrypted model attribute
            cache: Cache::store('redis'),
            logger: Log::channel('adobe-sign'),
            options: new ClientOptions(
                defaultSignatureLevel: SignatureLevel::from(strtoupper($tenant->signature_level)),
            ),
        );
    }
}

The data-centre cache key is a hash of the credentials, so tenants on different shards don't overwrite each other. Webhooks for these tenants still arrive at the package's route; add each tenant application's client id to webhooks.client_ids.

Common questions

• Using the clientFacade, injection and the manager's methods.
• WebhooksThe route, the handshake and queued listeners.