creator-cloud / php-sdk
Sign people in with their Creator ID, connect them to your Laravel app, and pay them.
Requires
- php: ^8.2
- ext-json: *
- ext-openssl: *
- firebase/php-jwt: ^6.10||^7.0
- laravel/framework: ^12.0||^13.0
- spatie/laravel-package-tools: ^1.16
Requires (Dev)
- larastan/larastan: ^3.0
- laravel/pint: ^1.17
- orchestra/testbench: ^10.0||^11.0
- pestphp/pest: ^3.0||^4.0||^5.0
- pestphp/pest-plugin-laravel: ^3.0||^4.0||^5.0
- phpstan/extension-installer: ^1.3
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Sign people in with their Creator ID, sign them up from your own form, pay them, and sign them out when Creator Cloud says so. For Laravel 12 and 13.
Route::get('/auth/creator-cloud', fn () => CreatorCloud::signIn()->redirect());
Route::get('/auth/creator-cloud/callback', function () {
$signedIn = CreatorCloud::signIn()->callback();
$user = User::firstOrCreate(
['creator_cloud_sub' => $signedIn->person->sub],
['name' => $signedIn->person->name(), 'email' => $signedIn->person->email],
);
Auth::login($user);
return redirect('/dashboard');
});
That's sign-in. State, nonce, code exchange, signature, issuer, audience, expiry: checked. You get a person you can trust, or an exception.
Creator Cloud signs people in. Your session stays yours. The developer docs explain the model. This package is the Laravel end of it.
Requirements
- PHP 8.2+
- Laravel 12 or 13
- An app registered on Creator Cloud, with its client id, secret and redirect URI
Install
composer require creator-cloud/php-sdk
Then .env:
CREATOR_CLOUD_CLIENT_ID=your-client-id
CREATOR_CLOUD_CLIENT_SECRET=your-client-secret
CREATOR_CLOUD_REDIRECT_URI=/auth/creator-cloud/callback
A path is made absolute with url(). Whatever it becomes has to match a redirect URI registered on your app, character for character.
Pointing at a local Creator Cloud:
CREATOR_CLOUD_ISSUER=https://account.creatorcloud.loc
CREATOR_CLOUD_API_URL=https://api.creatorcloud.loc
CREATOR_CLOUD_VERIFY_SSL=false
Want the config file? php artisan vendor:publish --tag=creator-cloud-config. You probably don't.
Sign in
Send them
return CreatorCloud::signIn()->redirect();
A fresh state and nonce go into the session, and the person goes to account.creatorcloud.io. Both routes need the web middleware, because the session is where the callback finds them again.
Inertia app? A redirect to another host can't be followed by XHR, so hand Inertia the address instead:
return Inertia::location(CreatorCloud::signIn()->url());
Options chain, and each signIn() starts clean:
CreatorCloud::signIn()->prompt('create')->redirect(); // "Create account": they make a Creator ID and come straight back
CreatorCloud::signIn()->prompt('login')->redirect(); // prove it again, even with a live session
CreatorCloud::signIn()->scopes('openid email')->redirect(); // ask for less than the config says
openid is always asked for. Leave it out and there's no ID token, and sign-in can't finish. So it can't be left out.
Bring them back
use CreatorCloud\Exceptions\SignInFailed;
try {
$signedIn = CreatorCloud::signIn()->callback();
} catch (SignInFailed $e) {
if ($e->wasCancelled()) {
return redirect('/')->with('info', 'No problem. Sign in whenever you like.');
}
report($e);
return redirect('/')->with('error', 'Sign-in failed. Try again.');
}
callback() checks the state, swaps the code for tokens, and verifies the ID token. State and nonce are single use, so a replayed callback fails.
$signedIn->person:
| Property | Scope | |
|---|---|---|
sub | openid | How your app knows them. Store it. Don't parse it. |
cloudId | profile | Their Creator ID, CC-8K2M-4QXD. Safe to show. |
givenName, familyName, name() | profile | |
picture | profile | Their one picture, the same everywhere they use their Creator ID. Null until they have one. |
country | profile | Null until they've told Creator Cloud |
email, emailVerified | email | |
amr | openid | How they proved it: pwd, email, otp, google, facebook, plus mfa for two or more |
authTime | openid | When they last proved it |
claims | Everything, including claims newer than this package |
$signedIn->tokens has accessToken, refreshToken, idToken and expiresAt.
SignInFailed::$error is the OAuth error Creator Cloud sent (access_denied, login_required, ...) or one of ours: invalid_state, missing_code, invalid_id_token. After a prompt=none check, needsInteraction() tells you to send them through the normal flow.
Their tokens, later
$tokens = CreatorCloud::signIn()->refresh($refreshToken); // null: they took their access back
$person = CreatorCloud::signIn()->userinfo($accessToken); // null: expired, or they removed your app
Both answer null for the expected "they're gone", and throw for anything that's your problem (a wrong secret, say).
Signing out
Signing someone out of your app ends your session. That's it. They stay signed in to Creator Cloud, the way leaving Spotify doesn't sign you out of Google.
Kiosk or shared tablet? End theirs too:
return redirect(CreatorCloud::signIn()->logoutUrl($idToken, '/signed-out'));
Back-channel logout
Sometimes Creator Cloud needs someone signed out of your app now. They hit "sign out everywhere", changed their password, got frozen, or removed your app. Creator Cloud posts a signed logout token to your server.
This package registers the route for you at POST /auth/creator-cloud/backchannel-logout, outside the web middleware so CSRF never eats it. Register https://your-app.example/auth/creator-cloud/backchannel-logout as your app's back-channel logout address. Then listen:
use CreatorCloud\Events\BackchannelLogoutReceived;
Event::listen(function (BackchannelLogoutReceived $event) {
$user = User::firstWhere('creator_cloud_sub', $event->sub);
if (! $user) {
return;
}
DB::table('sessions')->where('user_id', $user->id)->delete();
});
End every session they have. There's no session id in the token, on purpose.
That DB::table('sessions') line only works on the database session driver. On Redis or cookies, Laravel can't find a user's sessions. Stamp the user instead (sessions_valid_after), and have a middleware sign out any session that started before the stamp.
A listener that throws makes the route answer 500, and Creator Cloud tries again later. Anything that isn't a valid logout token for your app gets a 400 and no event.
Want the route somewhere else? Set CREATOR_CLOUD_BACKCHANNEL_LOGOUT_PATH. Want to write your own? Set it to an empty value and call CreatorCloud::signIn()->verifyLogoutToken($token), which hands back the sub or null.
API sign-up
For our own services, with the identities.create scope. Your form collects their details, Creator Cloud emails them a code, they type the code into your form.
$signUp = CreatorCloud::identities()->create([
'email' => 'thandi@example.com',
'first_name' => 'Thandi',
'last_name' => 'Mokoena',
'country' => 'ZA',
'external_id' => 'salt-user-48213',
]);
session(['signup_id' => $signUp->id]);
Every email gets the same answer and the same email. Nothing here tells you whether Thandi already had a Creator ID. That's the point.
use CreatorCloud\Exceptions\InvalidCode;
use CreatorCloud\Exceptions\SignUpClosed;
try {
$connection = CreatorCloud::identities()->verify(session('signup_id'), $request->input('code'));
} catch (InvalidCode $e) {
return back()->withErrors(['code' => "That's not it. {$e->attemptsLeft()} tries left."]);
} catch (SignUpClosed) {
return redirect('/join')->with('error', 'That code expired. Let\'s send a new one.');
}
// $connection->sub is yours now
Spaces in the code are stripped, because people type 418 207.
Connections
$connection = CreatorCloud::connections()->find($sub); // null if there's no such connection
$connection = CreatorCloud::connections()->disconnect($sub); // ends it from your side
$connection->isActive();
$connection->cloudId; // null unless they shared their profile
$connection->currencyCode; // null until they've said where they live
$connection->walletId; // apps that pay people: the wallet to pay them in
$connection->organisations; // and the agencies they're in that let you pay them
Their picture
A person has one picture, the way a Google account does. You get it as $person->picture at every sign-in. When they change it with you, send it back and it's their picture everywhere:
$connection = CreatorCloud::connections()->updatePicture($sub, $request->file('avatar'));
$connection->picture; // the address everyone gets from now on
An upload, a file or a path. JPEG, PNG or WebP, up to 5 MB, at least 96 pixels a side. Needs pictures.write, which we grant our own services. Creator Cloud keeps its own copy, so deleting yours later breaks nothing.
Server calls use a client-credentials token, minted once per scope and cached until just before it expires. A 401 (a regenerated secret revokes every token) mints a new one and tries once more.
Pay people
For our own services, with the credits.write scope and paying people switched on for your app.
You hold one funding balance with Creator Cloud, in US dollars, and pay people in whatever their wallet holds. A credit in another currency costs its dollar value at the day's rate, plus a 3% markup. A dollar credit costs itself. Amounts are integers in the currency's minor unit: 45000 in ZAR is R450.00, 2575 in USD is $25.75.
$funding = CreatorCloud::funding()->balance();
$funding->availableToCredit; // the balance plus any overdraft left: what the next credit draws on
$funding->topUpReference; // quote it on every transfer to our dollar account
Quote before you send
$quote = CreatorCloud::funding()->quote([
['amount' => 45000, 'currency_code' => 'ZAR'],
['amount' => 10000, 'currency_code' => 'GBP'],
]);
$quote->total; // US cents, the fee included
$quote->covered; // whether your balance covers it right now
$quote->credits[0]; // each credit's cost, and the rate it was priced at
Nothing is drawn and nothing is held. It's the day's price, until the day's rates move. Quote the very credits you're about to send, if you like: only the amounts and currencies go.
A credit
$connection = CreatorCloud::connections()->find($user->creator_cloud_sub);
$credit = CreatorCloud::credits()->create([
'reference' => "earning-{$earning->id}",
'wallet_id' => $connection->walletId,
'amount' => 45000,
'currency_code' => 'ZAR',
'description' => 'Spring campaign, 3 posts',
]);
$credit->id; // keep it, to release or reverse it later
$credit->funding->cost; // what your dollars paid
Read the wallet from their connection when you pay, not when the work starts. People move country, wallets retire, creators leave agencies. walletId is null until they've told Creator Cloud where they live. Paying their agency instead? Each of $connection->organisations has its own walletId.
The description is what they see on their statement, next to your app's name. The reference is yours, and it makes sending twice safe: after a timeout, send the very same credit again. You get the first one back, and nothing is drawn twice.
The currency is the wallet's, a safety check: it must match. '45000' from a form is read as 45000. Send integers, never floats: 0.29 * 100 is 28.999999999999996, and Creator Cloud refuses it.
Release and reverse
A credit lands withdrawable. Send 'release' => 'later' and it lands pending instead: in their wallet, theirs to withdraw once you release it. Or give it a date, 'release_at' => now()->addDays(14)->toIso8601String(), and Creator Cloud releases it on the day without you calling back.
$credit = CreatorCloud::credits()->release($creditId);
$credit = CreatorCloud::credits()->reverse($creditId); // the whole credit back
$credit->changed; // false when it was already released, or already reversed
$credit->funding->refunded; // what came back to your balance, at the rate it was booked
Both are safe to repeat. A reversal takes the amount out of their wallet whatever's in it: if they've already withdrawn it, the wallet goes below zero and their next earnings fill it. Any service fee stays with us. A reversed credit can't be released, and says so with a RequestFailed, credit_reversed.
Batches
Up to 200 credits in one call, each in its own wallet's currency. All or nothing.
$batch = CreatorCloud::batches()->create('payout-2026-10-week-2', [
['reference' => 'earning-77120', 'wallet_id' => $thandi->walletId, 'amount' => 45000, 'currency_code' => 'ZAR', 'description' => 'Spring campaign, 3 posts'],
['reference' => 'earning-77121', 'wallet_id' => $james->walletId, 'amount' => 10000, 'currency_code' => 'GBP', 'description' => 'Spring campaign, 1 story', 'release' => 'later'],
]);
Short of funds, a batch doesn't fail. It's saved as awaiting_funds, with $batch->funding->cost at today's price so you know what to top up, and it lands by itself once a top-up covers it. Until webhooks arrive, check on it:
$batch = CreatorCloud::batches()->find($batchId); // null if it isn't yours
$batch->isDelivered(); // then $batch->credits has every credit's id
$batch->problem; // why a waiting batch can't land, when it isn't money
CreatorCloud::batches()->cancel($batchId); // only while it waits: after that, batch_not_waiting
A delivered batch's credits are reversed one by one, like any other.
Wallets
$wallet = CreatorCloud::wallets()->find($walletId); // null for a wallet your app doesn't know
$wallet->payable; // whether a credit would be accepted right now
$wallet->owner->name; // who it belongs to. Never what's in it.
$wallet->activeWalletId; // a retired wallet's: the one that took over
When Creator Cloud says no
use CreatorCloud\Exceptions\CreditRefused;
try {
$credit = CreatorCloud::credits()->create($payment);
} catch (CreditRefused $e) {
return match ($e->errorCode) {
'insufficient_funds' => $this->topUpFirst($payment),
'wallet_retired' => $this->payInstead($e->activeWalletId(), $payment),
'rates_unavailable' => $this->tryAgainShortly($payment),
default => throw $e,
};
}
A refusal draws nothing and changes no wallet. CreditRefused is a RequestFailed, so branch on $errorCode:
errorCode | Means |
|---|---|
insufficient_funds | Your balance, overdraft included, doesn't cover it. Top up, and send it again. A batch waits instead. |
wallet_not_found | No wallet with that id that you may pay. Read their connection again. |
wallet_not_payable | They disconnected you, their organisation stopped you paying it, or the wallet is frozen |
wallet_retired | They moved, or their wallet changed currency. activeWalletId() is the one that took over. |
currency_mismatch | The wallet holds another currency |
duplicate_reference | Two lines in a batch share a reference, or one reuses a reference you already sent |
invalid_amount | Not a whole number above zero |
invalid_batch | Not between 1 and 200 credits |
not_a_paying_app | Paying people isn't switched on for your app |
reference_in_use | A different credit or batch has the reference: existingId(). A retry sends the very same thing, so this is a bug. |
rates_unavailable | The day's exchange rates aren't in yet. Try again in a few minutes. Dollar credits still go, and batches wait. |
A batch's refusal names its line: line() counts from 0, and reference() is that line's. A field that's missing or wrong is a plain RequestFailed with validation_failed, and $errors says which.
Wallets in the app
For our own services, with wallets.read and payouts.write (an admin grants them). Show a person their wallet on your screens and move money for them, so nobody gets sent somewhere else to see their own. Read it when the page loads and never keep it: Creator Cloud is the only copy.
$money = CreatorCloud::moneyFor($user->creator_cloud_sub);
$wallet = $money->wallet(); // their own, or null before they've said where they live
$wallet->available; // cents, theirs to withdraw
$wallet->blockedBy; // why no payout can go right now, in their terms, or null
$page = $money->statement($wallet->id); // newest first, every app's lines
$page->lines[0]->app; // ['code' => 'ofillo', 'name' => 'Ofillo', 'logo' => 'https://...'], null for a payout
$money->wallets() lists their organisations' wallets too, each with their role and canMoveMoney.
Paying out
$quote = $money->quote($wallet->id, 50000); // "You'll receive" $quote->sendAmount
$payout = $money->withdraw($wallet->id, 50000, "withdrawal-{$request->id}");
$payout->ref; // the bank reference on their statement
$money->cancel($payout->id); // until finance takes it
Check they signed in recently before you ask: that's your job, the way it's ours on our own pages. The reference is yours, so asking twice after a timeout makes one payout. It goes to their primary payout method, or to one of their own you name (withdraw($walletId, $amount, $reference, $payoutMethodId)). Never anywhere else.
A refusal is a PayoutRefused: payout_refused carries a message to show them ("Add a payout method first."), not_allowed means their role in the organisation can't move its money.
Changing payout details
No app can change where money goes. Send them to Creator Cloud instead:
use CreatorCloud\Money\LinkPurpose;
$link = $money->link($wallet->id, LinkPurpose::PAYOUT_METHODS, route('wallet.payouts'));
return Inertia::location($link->url);
They sign in as themselves, add or change a payout method under your app's name, and come back to your address with cc_link and cc_result (done, or expired for a link that was used or too old). A link works once, for ten minutes, and only returns to a host your app has a redirect URI on. $money->payoutMethods($wallet->id) lists them masked (FNB ••0991), the primary first.
Webhooks
Creator Cloud posts payout, payout method, verification and credit events to the address staff set for your app, signed with your CREATOR_CLOUD_WEBHOOK_SECRET:
Route::post('/creator-cloud/webhook', function (Request $request) {
$event = CreatorCloud::webhooks()->verify($request->getContent(), $request->header('Creator-Cloud-Signature'));
match ($event->type) {
'payout.paid' => $this->tellThemItsSent($event->sub(), $event->data),
'payout.failed' => $this->tellThemItFailed($event->sub(), $event->data),
default => null,
};
return response()->noContent();
});
verify() throws InvalidSignature for a post that isn't yours or is more than five minutes old. Each event's id is unique: handle each once. Missed some? CreatorCloud::webhooks()->events($lastIdYouHandled).
Errors
Everything thrown is a CreatorCloud\Exceptions\CreatorCloudException. The ones you'll meet:
| Exception | When |
|---|---|
SignInFailed | The callback couldn't sign anyone in. Read $error. |
RequestFailed | Creator Cloud answered with an error, or couldn't be reached (status 0, errorCode connection_failed). |
InvalidCode, SignUpClosed | API sign-up. Both are RequestFailed. |
CreditRefused | Paying someone was refused, and nothing was drawn. A RequestFailed, with activeWalletId(), line(), reference() and existingId(). |
InvalidConfiguration | A missing setting, or a callback route without a session. Names the fix. |
Branch on RequestFailed::$errorCode, never on the message. Messages get reworded. $errors maps fields to what's wrong with them on a 422.
Testing
CreatorCloud::fake() stands in for Creator Cloud's sign-in. The tokens are real, signed with a throwaway key and checked by the same code that runs in production. No mocks of this package's internals, and nothing to keep in sync.
use CreatorCloud\Facades\CreatorCloud;
it('signs Max in', function () {
$fake = CreatorCloud::fake();
$redirect = $this->get('/auth/creator-cloud');
$callback = $fake->approve($redirect, ['sub' => '64f1c0e2a7b3c91d2e4f5a6b', 'given_name' => 'Max']);
$this->get($callback)->assertRedirect('/dashboard');
$this->assertAuthenticated();
});
| Method | Gives you |
|---|---|
approve($redirect, $claims) | The callback URL after they approved. Your claims replace the defaults (Max Fourie, max@example.com, CC-8K2M-4QXD). |
deny($redirect) | The callback URL after they said no |
logoutToken($sub, $claims) | A logout token to post to /auth/creator-cloud/backchannel-logout |
idToken($claims) | A signed ID token, for when you need to build a bad one |
Claims you pass win, so breaking things on purpose is one line:
$fake->approve($redirect, ['exp' => time() - 3600]); // expired
$fake->approve($redirect, ['aud' => 'someone-else']); // meant for another app
$fake->approve($redirect, ['nonce' => 'nope']); // replayed from another browser
The fake answers the token, userinfo and signing-key endpoints. /v1 calls, paying people included, stay yours to fake with Http::fake(), like any other API.
Config
| Key | Env | Default |
|---|---|---|
client_id | CREATOR_CLOUD_CLIENT_ID | |
client_secret | CREATOR_CLOUD_CLIENT_SECRET | |
redirect_uri | CREATOR_CLOUD_REDIRECT_URI | /auth/creator-cloud/callback |
scopes | CREATOR_CLOUD_SCOPES | openid profile email |
backchannel_logout_path | CREATOR_CLOUD_BACKCHANNEL_LOGOUT_PATH | /auth/creator-cloud/backchannel-logout |
issuer | CREATOR_CLOUD_ISSUER | https://account.creatorcloud.io |
api_url | CREATOR_CLOUD_API_URL | https://api.creatorcloud.io |
verify_ssl | CREATOR_CLOUD_VERIFY_SSL | true |
timeout | CREATOR_CLOUD_TIMEOUT | 10 seconds |
cache_store | CREATOR_CLOUD_CACHE_STORE | Your default store |
Settings are checked when they're first needed, not at boot. An app that hasn't set its credentials yet still runs everything else.
Signing keys are cached for an hour. A token signed with a key nobody's seen means Creator Cloud rotated its keys, so they're fetched again, at most once a minute. A stream of junk tokens can't turn your app into a JWKS hammer.
Not yet
- Public clients. Mobile and single-page apps can't keep a secret. PKCE comes when Creator Cloud decides who may sign in without one.
License
MIT. See LICENSE.md.