OAuth: connect user accounts

When to use OAuth

Use OAuth when the agreements should belong to your users' Acrobat Sign accounts: they appear in their Acrobat Sign dashboard, emails come from them, and their own plan and settings apply. A sales tool, an HR product or a property platform where each customer already pays for Acrobat Sign are typical cases. If everything is sent from one account you own, an Integration Key is simpler; see Integration Key or OAuth?

Set up the Adobe application

1. Create an API application

   In Acrobat Sign go to Account → Acrobat Sign API → API Applications and create one. Note its client id (application id) and client secret.

2. Configure OAuth on it

   Add your callback as a redirect URI, exactly as your app will send it, for example https://app.example.com/adobe-sign/oauth/callback. Enable the scopes you will request, with the modifier (self, group or account) you need. Adobe refuses requests for scopes the application doesn't allow.

3. Add the credentials to .env

   ADOBE_SIGN_CLIENT_ID=CBJCHBCAABAA...
   ADOBE_SIGN_CLIENT_SECRET=your-client-secret
   # Only if the URL differs from route('adobe-sign.oauth.callback'):
   # ADOBE_SIGN_REDIRECT_URI=https://app.example.com/adobe-sign/oauth/callback

4. Create the token table

   php artisan vendor:publish --tag=adobe-sign-migrations
   php artisan migrate

The routes

The package registers two GET routes when oauth.routes is true (the default):

Three config keys shape them:

• oauth.route_prefix (default adobe-sign/oauth) changes the URIs. If you change it, update the redirect URI on the Adobe application too.
• oauth.route_middleware (default ['web', 'auth']). web is required because the state lives in the session; an authentication middleware is required because tokens are stored under the signed-in user. Without a user the callback aborts with 401.
• oauth.redirect_after (default /) is where the user lands after connecting. Point it at your integrations or settings page.

Add the button wherever users manage integrations:

@if (AdobeSign::isConnected(auth()->user()))
    <p>Acrobat Sign is connected.</p>
    <form method="POST" action="{{ route('integrations.acrobat-sign.disconnect') }}">
        @csrf @method('DELETE')
        <button>Disconnect</button>
    </form>
@else
    <a href="{{ route('adobe-sign.oauth.redirect') }}">Connect Acrobat Sign</a>
@endif

The global AdobeSign alias is the facade, so it works in Blade without an import.

The connect flow, step by step

1. Redirect with a fresh state

   OAuthController::redirect() generates 64 random hex characters with OAuthClient::generateState(), stores them in the session under adobe_sign_oauth_state, and redirects to https://secure.adobesign.com/public/oauth/v2 with response_type=code, your client id, redirect URI, scopes and the state.

2. The user consents at Adobe

   They sign in to Acrobat Sign and see the permissions your scopes ask for. Adobe then redirects to your callback with a one-time code (valid for five minutes), the state, and api_access_point: the data centre their account lives on.

3. Check the state, once

   The callback pulls the state from the session, so it can be used only once, and compares it in constant time with the one in the URL. A mismatch, a replayed callback URL or a missing code ends with 400. This is the CSRF protection of the flow: a link someone else started can't attach their Acrobat Sign account to your user.

4. Exchange the code on the right data centre

   The core validates that api_access_point is an Adobe host before sending anything to it (a forged value gets a 400 and your client secret never leaves the app), then posts the code and secret to {api_access_point}oauth/v2/token.

5. Store, announce, redirect

   The tokens are stored through the bound TokenStore under AdobeSign::userKey($user), OAuthConnected is dispatched, and the user is redirected to oauth.redirect_after.

What the callback answers when something goes wrong

These are plain abort() responses, so your app's error pages render them. To show friendlier messages, render custom errors/400.blade.php and errors/403.blade.php views, or disable the routes and write your own controller around AdobeSign::oauth().

Where tokens live

The default TokenStore is Conceptlz\AdobeSign\Laravel\EloquentTokenStore, which reads and writes the adobe_sign_tokens table through the Conceptlz\AdobeSign\Laravel\Models\AdobeSignToken model. One row per user key:

The model casts both tokens with Laravel's encrypted cast and hides them from toArray() and JSON, so a stray dd($token) or API resource won't expose them. A database dump alone is useless without APP_KEY.

Using your own token store

Bind any implementation of Conceptlz\AdobeSign\Auth\TokenStore (two methods, get() and put()) in a service provider and the package uses it instead, for the routes and for forUser() alike:

use Conceptlz\AdobeSign\Auth\{AccessToken, TokenStore};

final class TeamSettingsTokenStore implements TokenStore
{
    public function get(string $key): ?AccessToken
    {
        $json = TeamSetting::where('key', "adobe-sign:$key")->value('encrypted_value');

        return $json === null ? null : AccessToken::fromArray(json_decode(decrypt($json), true));
    }

    public function put(string $key, AccessToken $token): void
    {
        TeamSetting::updateOrCreate(
            ['key' => "adobe-sign:$key"],
            ['encrypted_value' => encrypt(json_encode($token->toArray()))],
        );
    }
}

// AppServiceProvider::register()
$this->app->singleton(TokenStore::class, TeamSettingsTokenStore::class);

The OAuthConnected event

Conceptlz\AdobeSign\Laravel\Events\OAuthConnected fires once per successful connection, after the tokens are stored. It has three read-only properties:

A listener is the place to record the connection on your side, for example which Acrobat Sign user connected:

use Conceptlz\AdobeSign\Laravel\AdobeSignManager;
use Conceptlz\AdobeSign\Laravel\Events\OAuthConnected;

final class RecordAcrobatSignConnection
{
    public function __construct(private readonly AdobeSignManager $adobe)
    {
    }

    public function handle(OAuthConnected $event): void
    {
        $me = $this->adobe->forUser($event->key)->users()->me();

        $event->user->forceFill([
            'adobe_sign_email' => $me->getEmail(),
            'adobe_sign_connected_at' => now(),
        ])->save();
    }
}

This listener runs synchronously during the callback, which is fine for one quick call. If it does more, make it ShouldQueue and rely on $event->key rather than the user object, since the event doesn't use SerializesModels.

Acting as a connected user

use Conceptlz\AdobeSign\Laravel\Facades\AdobeSign;

if (! AdobeSign::isConnected($user)) {
    return redirect()->route('adobe-sign.oauth.redirect');
}

$agreementId = AdobeSign::forUser($user)->agreements()->create($info);

• forUser() accepts a user model or the key itself (42, 'team:7'). In queued jobs pass the key, since there is no signed-in user there.
• isConnected() only checks that a row exists. It doesn't call Adobe.
• ADOBE_SIGN_AUTH=oauth makes the facade's forwarded calls and the injected AdobeSign use forUser(auth()->user()) automatically, which is convenient when every request is a signed-in user acting for themselves.
• Data centres come from the token's api_access_point, so users on na1 and eu1 work side by side without extra configuration.

One connection per team

By default the key is the user's auth identifier. If a whole team shares one Acrobat Sign account, change the mapping once, in a service provider's boot():

use Conceptlz\AdobeSign\Laravel\AdobeSignManager;

AdobeSignManager::resolveUserKeyUsing(fn ($user) => 'team:'.$user->current_team_id);

Now the callback stores tokens under team:7, and forUser($anyTeamMember) uses them. The resolver is static and applies to the whole process; set it at boot rather than per request. When you pass a key directly, pass the resolved form ('team:7').

Refreshing tokens

Access tokens last about an hour. You never refresh them yourself: the core's OAuthTokenProvider refreshes a token 60 seconds before it expires, or once after the API rejects it with 401, and writes the new token back to the store. Adobe doesn't rotate refresh tokens, so two processes refreshing the same user at once both end up valid, with no locking.

What can't be fixed automatically is a dead refresh token: Adobe expires it after 60 days without use, and it dies when the user revokes access or the account changes. The next call then throws Conceptlz\AdobeSign\Exception\OAuthException, with an $errorCode such as INVALID_TOKEN or EXPIRED_TOKEN (or NO_TOKEN when nothing is stored). The only cure is to connect again:

use Conceptlz\AdobeSign\Exception\OAuthException;

try {
    $id = AdobeSign::forUser($user)->agreements()->create($info);
} catch (OAuthException $e) {
    report($e);   // the message never contains the token or secret

    return redirect()->route('adobe-sign.oauth.redirect')
        ->with('status', 'Your Acrobat Sign connection has expired. Please connect again.');
}

To keep rarely used connections alive, a scheduled command can make a cheap call such as users()->me() for each connected user every few weeks; any successful refresh restarts the 60-day clock.

Disconnecting

Disconnecting has two halves: revoke the token at Adobe, so it stops working there, and delete it from your table. EloquentTokenStore::forget() does the second; it isn't part of the TokenStore interface, so check the type if you might swap stores.

use Conceptlz\AdobeSign\Exception\AdobeSignException;
use Conceptlz\AdobeSign\Laravel\AdobeSignManager;
use Conceptlz\AdobeSign\Laravel\EloquentTokenStore;
use Illuminate\Http\Request;

final class DisconnectAcrobatSignController
{
    public function __invoke(Request $request, AdobeSignManager $adobe)
    {
        $key = $adobe->userKey($request->user());
        $tokens = $adobe->tokens();

        if ($token = $tokens->get($key)) {
            try {
                $adobe->oauth()->revoke($token);   // revoking either token revokes the pair
            } catch (AdobeSignException $e) {
                report($e);                         // still remove it locally
            }
        }

        if ($tokens instanceof EloquentTokenStore) {
            $tokens->forget($key);
        }

        return back()->with('status', 'Acrobat Sign disconnected.');
    }
}

Webhooks created with that user's token keep running at Adobe until you delete them; do that first with forUser($user)->webhooks()->delete($id) if you track their ids.

Choosing scopes

Scopes limit what a token can do. Each has a modifier: :self (the user's own resources, the default), :group (their group's, for group admins) or :account (the whole account, for account admins). The package requests these by default:

user_login:self agreement_read:self agreement_write:self agreement_send:self webhook_read:self webhook_write:self

That covers sending, tracking and downloading your user's own agreements and registering webhooks for them. Add a scope only for a feature that needs it, for example library templates or web forms, and enable it on the Adobe application first:

ADOBE_SIGN_SCOPES="user_login:self agreement_read:self agreement_write:self agreement_send:self webhook_read:self webhook_write:self library_read:self"

Scopes are fixed when the user consents. After you change them, existing users keep their old grant until they connect again, so prompt them to reconnect for the new feature. Asking for :account scopes only works for account admins, and Adobe shows the user what they grant; narrow scopes make the consent screen less alarming.

Common questions

• WebhooksReceive signing progress for your users' agreements.
• ReferenceEvents, routes, the model and the migration at a glance.