id/README.md

Anikeen ID

PHP Anikeen ID API Client for Laravel 12+

Sign in with Anikeen ID and let your users pay with their Anikeen ID account: one-off orders, subscriptions and physical goods, with invoices, VAT and payment handled by Anikeen ID.

Table of contents

1. Installation
2. Configuration
3. Sign in with Anikeen ID
4. Payments
5. Trusted apps
6. User profiles
7. Preferences
8. API authentication
9. General
10. Examples
11. Documentation
12. Development

Installation

composer require anikeen/id

Configuration

Register your app in Anikeen ID first. You need:

• an OAuth client with your callback URL as redirect URI (e.g. https://shop.test/auth/callback),
• a webhook endpoint (e.g. https://shop.test/webhooks/anikeen) if you sell something; Anikeen ID shows its signing secret whsec_…,
• optionally a logo, shown to your users on the login and confirmation pages.

Add the credentials to your .env file:

ANIKEEN_ID_KEY=
ANIKEEN_ID_SECRET=
ANIKEEN_ID_CALLBACK_URL=http://localhost/auth/callback
ANIKEEN_ID_WEBHOOK_SECRET=

To switch from production to staging use following variable:

ANIKEEN_ID_MODE=staging

You will need to add an entry to the services configuration file so that after config files are cached for usage in production environment (Laravel command artisan config:cache) all config is still available.

Add to config/services.php file:

'anikeen' => [
    'mode' => env('ANIKEEN_ID_MODE'),
    'client_id' => env('ANIKEEN_ID_KEY'),
    'client_secret' => env('ANIKEEN_ID_SECRET'),
    'redirect' => env('ANIKEEN_ID_CALLBACK_URL'),
    'base_url' => env('ANIKEEN_ID_BASE_URL'),
    'webhook_secret' => env('ANIKEEN_ID_WEBHOOK_SECRET'),
],

Sign in with Anikeen ID

Event Listener

Since Laravel 11, the default EventServiceProvider provider was removed. Instead, add the listener using the listen method on the Event facade, in your AppServiceProvider boot method:

public function boot(): void
{
    Event::listen(function (\SocialiteProviders\Manager\SocialiteWasCalled $event) {
        $event->extendSocialite('anikeen', \Anikeen\Id\Socialite\Provider::class);
    });
}

User model

Your users table needs the user's Anikeen ID and their tokens:

Schema::table('users', function (Blueprint $table) {
    $table->string('anikeen_id')->nullable()->unique();
    $table->text('anikeen_id_access_token')->nullable();
    $table->text('anikeen_id_refresh_token')->nullable();
});

Add the Billable trait to the user model. Keep the tokens encrypted and out of JSON:

use Anikeen\Id\Billable;

class User extends Authenticatable
{
    use Billable;

    protected $hidden = ['password', 'remember_token', 'anikeen_id_access_token', 'anikeen_id_refresh_token'];

    protected function casts(): array
    {
        return [
            'anikeen_id_access_token' => 'encrypted',
            'anikeen_id_refresh_token' => 'encrypted',
        ];
    }
}

All user methods ($user->orders(), $user->subscriptions(), …) call the API with the user's access token from anikeen_id_access_token.

Login and callback

Ask for the scopes your app needs (see Scope). To sell orders and subscriptions, a shop typically asks for:

use Laravel\Socialite\Facades\Socialite;

Route::get('auth/redirect', fn () => Socialite::driver('anikeen')
    ->scopes(['user:read', 'addresses:read', 'orders', 'subscriptions'])
    ->redirect());

Route::get('auth/callback', function () {
    $account = Socialite::driver('anikeen')->user();

    $user = User::updateOrCreate(['anikeen_id' => $account->getId()], [
        'name' => $account->getName() ?: $account->getNickname(),
        'email' => $account->getEmail(),
        'anikeen_id_access_token' => $account->token,
        'anikeen_id_refresh_token' => $account->refreshToken,
    ]);

    Auth::login($user, remember: true);

    return redirect()->intended('/');
});

Access tokens expire. Get a new one with the refresh token (or send the user through the login again):

$result = app(\Anikeen\Id\AnikeenId::class)->refreshToken($user->anikeen_id_refresh_token);

if ($result->success()) {
    $user->update([
        'anikeen_id_access_token' => $result->data()->access_token,
        'anikeen_id_refresh_token' => $result->data()->refresh_token,
    ]);
}

Scopes

Scopes follow one schema: resource grants full access, resource:read read-only access and resource:client access to what the app or token created itself. All of them are constants on Anikeen\Id\Enums\Scope, e.g. Scope::ORDERS_READ.

The Anikeen Console accepts personal access tokens and OAuth tokens (no client credentials) with these scopes for its product and reseller APIs:

Scope	Constant	Grants
products:read	Scope::PRODUCTS_READ	view the products of your teams
reseller-customers:read	Scope::RESELLER_CUSTOMERS_READ	view a reseller team's customers and invitations
reseller-customers	Scope::RESELLER_CUSTOMERS	manage customers: invite, resend, remove logins (includes reading)
reseller-grants	Scope::RESELLER_GRANTS	grant customers access to products and revoke it
reseller-orders	Scope::RESELLER_ORDERS	order products for customers, charged right away

A full reseller scope includes reading. user and * do not open the reseller endpoints: the token has to carry the reseller scope itself. For the product APIs there is only products:read; changing products needs user.

Changing the user's profile needs Scope::USER (user); user:read only reads.

Anikeen ID's preferences use these scopes:

Scope	Constant	Grants
preferences:read	Scope::PREFERENCES_READ	read the user's shared preferences (global)
preferences	Scope::PREFERENCES	read and change them
preferences:client	Scope::PREFERENCES_CLIENT	app tokens: the preferences of any user, in the namespaces Anikeen registered for the app

Change the default access token / refresh token field name

If your access / refresh token fields differ from the default anikeen_id_access_token / anikeen_id_refresh_token, you can specify the field name in the AppServiceProvider boot method:

use Anikeen\Id\AnikeenId;

public function boot(): void
{
    AnikeenId::useAccessTokenField('anikeen_id_access_token');
    AnikeenId::useRefreshTokenField('anikeen_id_refresh_token');
}

Payments

Which way fits?

You want to sell	Use	Token	Who starts the payment
One-off purchases (digital or physical goods)	Orders	user	the user, on Anikeen ID
Something that recurs (a pass, a plan)	Subscriptions	user	the user, on Anikeen ID
Several subscriptions in one step	Checkout sessions	user or app	the user, on Anikeen ID
Usage billing from your backend, without the user online	App subscriptions	app	your app (trusted apps only)
Single items on the user's monthly bill (e.g. a shipped item)	Charges	app	your app (trusted apps only)

Most apps are third-party apps: they create an order or subscription as a draft, send the user to Anikeen ID to confirm and pay, and get the user back afterwards. Anikeen ID shows the items, asks for missing addresses, takes the payment and writes the invoice. Trusted apps (operated by Anikeen) can also charge directly; see Trusted apps. For a per-item charge on the user's monthly bill use createChargeForUser(), not createOrderForUser(): an order is a separate one-off purchase, charged on its own.

The flow, as in a typical shop:

1. The user signs in with Anikeen ID (above).
2. Your app creates the order: $user->orders()->create([...]).
3. Redirect the user to $order->confirmationUrl($returnUrl).
4. The user confirms and pays on Anikeen ID, then comes back to $returnUrl?status=…&order=….
5. Your app reads the order through the API (never trust the query string) and shows the result.
6. The order.completed webhook arrives; fulfil the order there.

Selling an order

use Anikeen\Id\Exceptions\ResourceException;

$order = $user->orders()->create([
    'billing_address_id' => $user->getUserData()->billing_address_id,
    'items' => [
        ['type' => 'digital', 'name' => 'Sticker pack', 'unit' => 'piece', 'units' => 1, 'gross_price' => '9.99'],
    ],
]);

$shopOrder = ShopOrder::create(['user_id' => $user->id, 'anikeen_id' => $order->id, 'status' => $order->status]); // your own order model

return redirect()->away($order->confirmationUrl(route('orders.return', $shopOrder)));
// later: https://shop.test/orders/1/return?status=completed&order=01J…

When the user has no billing address on Anikeen ID yet, pass one instead of the ID. A name and the country are enough; the user completes it on the confirmation page:

'billing_address' => ['first_name' => 'Ada', 'last_name' => 'Lovelace', 'country_iso' => 'DE', 'email' => $user->email],

Back in your app, read the order to know its state:

Route::get('orders/{shopOrder}/return', function (ShopOrder $shopOrder) {
    $order = auth()->user()->orders()->find($shopOrder->anikeen_id);

    $shopOrder->update(['status' => $order->status]);

    return redirect()->route('orders.show', $shopOrder);
});

The order's status:

status	Meaning
draft	Created, not confirmed by the user yet
pending	Confirmed, the payment is still processing
completed	Paid
cancelled	The user cancelled, or it wasn't confirmed within 24 hours

return_url must have the origin of one of your app's redirect URIs. The status in its query string (completed, pending or cancelled) is only a hint for the message you show.

checkout() on such a draft throws ConfirmationRequiredException; its confirmationUrl points to the same page. Trusted apps keep checking out directly.

Prices and VAT

Anikeen ID calculates VAT from the user's billing address and the item type:

type	For	VAT in Germany
digital	Downloads, streams, services	19 %
physical	Goods you ship	19 %
physical-reduced	Goods with the reduced rate (books, event tickets, …)	7 %

Give each item either gross_price (VAT included, what the user pays) or price (net), per unit. unit is piece or onetime for orders; units is the quantity. Subscription prices are always net per unit (hour, day, week, month, year).

To show a total before the user confirms, ask for a preview:

$preview = app(\Anikeen\Id\AnikeenId::class)->createOrderPreview([
    'country_iso' => 'DE',
    'items' => [['type' => 'physical', 'name' => 'T-shirt', 'gross_price' => '24.90', 'unit' => 'piece', 'units' => 1]],
])->shift();

$preview->gross_total;

Physical goods and shipments

Physical goods need a shipping address (first_name, last_name, address, postal_code, city, country_iso). The user can change both addresses on the confirmation page, so read the shipping address from the order (or the order.completed webhook) before you ship. An item's image_url is copied to Anikeen ID and stays visible on the order and invoice:

$order = $user->orders()->create([
    'billing_address_id' => $addressId,
    'shipping_address' => ['first_name' => 'Ada', 'last_name' => 'Lovelace', 'address' => 'Main St', 'house_number' => '1', 'postal_code' => '10115', 'city' => 'Berlin', 'country_iso' => 'DE'],
    'items' => [
        ['type' => 'physical', 'name' => 'T-shirt', 'unit' => 'piece', 'units' => 1, 'gross_price' => '24.90', 'image_url' => 'https://shop.test/img/shirt.png'],
        ['type' => 'physical-reduced', 'name' => 'Artbook', 'unit' => 'piece', 'units' => 1, 'gross_price' => '19.95'],
    ],
]);

Once a paid order is sent, create a shipment. Anikeen ID adds its delivery note to the user's order documents (with the tracking link), mails it to the user ('notify_customer' => false if your shop sends its own mail) and sends order.shipped to your webhook endpoints. Without items, everything physical that is left is shipped; partial deliveries name the items:

$order = $user->orders()->find($orderId);

$shipment = $order->shipments()->create([
    'carrier' => 'DHL',
    'tracking_number' => '00340434161234567890',
    'tracking_url' => 'https://www.dhl.de/…?piececode=00340434161234567890',
    // 'items' => [['order_item_id' => $itemId, 'units' => 1]],
]);

$shipment->number;          // LS-2026-0001
$shipment->deliveryNote();  // the delivery note as PDF

To know what is left to ship, compare the order's items with its shipments:

$items = $order->orderItems()->toArray();     // id, type, name, units, …
$shipments = $order->shipments()->toArray();  // each with items: [{order_item_id, units}]

Only the app that created the order (or a trusted app) can ship it, and only once it is paid.

Subscriptions

Subscriptions work like orders: create a draft, let the user confirm it, read it back.

$subscription = $user->subscriptions()->create([
    'name' => 'Pixel Stream Pass',
    'description' => 'All streams, every month',
    'unit' => 'month',
    'price' => 6.714286,           // net per unit, 7.99 with 19 % VAT
]);

return redirect()->away($subscription->confirmationUrl(route('pass.return')));
// later: https://shop.test/pass/return?status=completed&subscription=01J…

After the return, read the subscription and check its state:

$subscription = $user->subscriptions()->find($id);

if ($subscription->isActive()) {
    // grant access
}

status() returns one of the Anikeen\Id\Enums\SubscriptionStatus constants (the API sends the same value as status):

status()	Meaning	isActive()
draft	Created, not confirmed by the user yet	no
trial	Running, in its trial period	yes
active	Running and billed	yes
paused	Runs until the paid period ends, then expires (resume() to continue)	yes
cancelling	Runs until a scheduled cancellation takes effect	yes
expired	Paused and ran out; resume() starts a new period	no
cancelled	Cancelled for good	no

There are shortcuts for each: isDraft(), isTrial(), isPaused(), isCancelling(), isExpired(), isCancelled(). App subscriptions (appSubscriptions()) have the same methods.

Free trials

Give a subscription a free trial with trial_days (1–365, counted from the user's confirmation or the checkout) or a fixed trial_ends_at (ISO 8601, in the future), not both. The subscription starts right away with status trial and nothing billed; the first period is billed when the trial ends. trial_once refuses the trial if the user already had one with your app in the same group (422 when creating, 409 trial_already_used when checking out):

$subscription = $user->subscriptions()->create([
    'name' => 'Pixel Stream Pass',
    'unit' => 'month',
    'price' => 6.714286,
    'trial_days' => 14,
    'trial_once' => true,
]);

A few days before the trial ends, Anikeen ID sends subscription.trial_will_end (EventType::SUBSCRIPTION_TRIAL_WILL_END), e.g. to remind the user; data.payment_method_missing tells you whether the user still has to add a payment method. Cancelling during the trial bills nothing. Trials work the same for app subscriptions and per subscription of a checkout session.

By default the user needs a payment method to confirm a trial. With trial_payment_method TrialPaymentMethod::OPTIONAL (only together with a trial; TrialPaymentMethod::REQUIRED is the default) the user can confirm it without one, as long as nothing else has to be paid: in a checkout session every subscription has to be such a trial. The confirmation page tells the user to add a payment method before the trial ends. If there is still none then, the subscription is cancelled at the trial's end instead of billed: status cancelled, cancellation_reason CancellationReason::TRIAL_ENDED_WITHOUT_PAYMENT_METHOD, subscription.cancelled with data.reason set to the same value, and no subscription.renewed. Adding a payment method later doesn't bring it back – create a new subscription. The trial still counts for trial_once. Anikeen ID also mails the user a few days before such a trial ends without a payment method.

use Anikeen\Id\Enums\CancellationReason;
use Anikeen\Id\Enums\TrialPaymentMethod;
use Anikeen\Id\Webhooks\EventType;

$subscription = $user->appSubscriptions()->create([
    'group' => $teamId,
    'name' => 'Uptimr Pro',
    'unit' => 'month',
    'price' => 19.00,
    'trial_days' => 14,
    'trial_payment_method' => TrialPaymentMethod::OPTIONAL,
]);

// in your webhook handler
$data = $event['data'];

match ($event['type']) {
    EventType::SUBSCRIPTION_TRIAL_WILL_END => $data['payment_method_missing']
        ? Reminder::addPaymentMethod($data['object']['id'])
        : null,
    EventType::SUBSCRIPTION_CANCELLED => $data['reason'] === CancellationReason::TRIAL_ENDED_WITHOUT_PAYMENT_METHOD
        ? Pass::downgrade($data['object']['id'])
        : Pass::revoke($data['object']['id']),
    default => null,
};

Discounts

A discount (e.g. a coupon) lowers the price of billed periods: every discounted period gets a negative line with the label next to its usage on the same bill, until the discount ends.

$subscription = $user->subscriptions()->create([
    'name' => 'Pixel Stream Pass',
    'unit' => 'month',
    'price' => 6.714286,
    'discount' => [
        'label' => 'SUMMER20',         // shown to the user, e.g. the coupon code
        'percent_off' => 20,           // or 'amount_off' => 1.50 (net, per period)
        'duration' => 'repeating',     // once, repeating or forever
        'duration_in_periods' => 3,    // only for repeating
    ],
]);

$subscription->discount;               // {label, percent_off, amount_off, duration, duration_in_periods, periods_remaining}

A period is one unit of the subscription (a month for monthly prices). A free trial isn't a billed period: the discount starts with the first paid one. periods_remaining counts down with every billed period (null for forever, 0 once it ended); then subscription.discount_ended (EventType::SUBSCRIPTION_DISCOUNT_ENDED) is sent. A discount can't be combined with a monthly_cap. It is set when the subscription is created (app subscriptions and checkout sessions alike) and changed afterwards with change(). A resize (predecessor_id) doesn't carry it over: send the successor the rest ('duration' => 'repeating', 'duration_in_periods' => $old->discount->periods_remaining).

Webhooks

Anikeen ID sends order.*, subscription.* and checkout.* events to the webhook endpoints of your app (see EventType for all of them). Verify each request with the raw body and answer 2xx within 10 seconds; failed deliveries are retried for about three days.

Exclude the route from CSRF protection in bootstrap/app.php:

->withMiddleware(function (Middleware $middleware) {
    $middleware->validateCsrfTokens(except: ['webhooks/*']);
})

use Anikeen\Id\Exceptions\SignatureVerificationException;
use Anikeen\Id\Webhooks\EventType;
use Anikeen\Id\Webhooks\Webhook;

Route::post('webhooks/anikeen', function (Request $request) {
    try {
        $event = Webhook::constructEvent($request->getContent(), $request->header('Anikeen-Signature'), config('services.anikeen.webhook_secret'));
    } catch (SignatureVerificationException) {
        abort(400);
    }

    if (! ProcessedEvent::firstOrCreate(['id' => $event['id']])->wasRecentlyCreated) {
        return response()->noContent(); // already handled
    }

    $object = $event['data']['object'];

    match ($event['type']) {
        EventType::ORDER_COMPLETED => Shop::fulfil($object['id'], $object['shipping_address']),
        EventType::ORDER_CANCELLED => Shop::release($object['id']),
        EventType::SUBSCRIPTION_ACTIVATED => Pass::grant($object['id']),
        EventType::SUBSCRIPTION_CANCELLED => Pass::revoke($object['id']),
        EventType::CHECKOUT_COMPLETED => Panel::provision($object['subscription_ids']),
        default => null,
    };

    return response()->noContent();
});

data.object is the order, subscription or checkout session as the API returns it. Events can arrive more than once or out of order: use $event['id'] to skip duplicates, and reload the object through the API when the current state matters. The admin panel can send a webhook.test event to check your endpoint.

subscription.renewed (EventType::SUBSCRIPTION_RENEWED) is sent once for every period booked on the user's monthly order, the first one included, with $event['data']['period']: {subscription_id, period_start, period_end, periods, first_period, unit, order_id, order_item_id, items, currency_iso, net_amount} (net_amount after a discount). first_period is true for the subscription's first paid period (the checkout, sent after subscription.activated, or the first period after a free trial) and false for every later one (renewals, resuming an expired subscription, a unit change applied right away). Hourly subscriptions renew every hour, so this event is opt-in: select it explicitly for your endpoint, * doesn't include it.

if ($event['type'] === EventType::SUBSCRIPTION_RENEWED) {
    $period = $event['data']['period'];
    // e.g. a commission per paid period; the first one may count differently
    Commission::record($period['subscription_id'], $period['net_amount'], first: $period['first_period']);
}

order.* events list the order's items and invoice like app orders.

billing_limit.reached and billing_limit.available (EventType::BILLING_LIMIT_REACHED, BILLING_LIMIT_AVAILABLE) tell trusted apps that a user's billing limit was reached or has room again; they are opt-in like subscription.renewed, see Charges and billing limit.

order.refunded (EventType::ORDER_REFUNDED) is sent when money was given back for an order (a refund or a partial cancellation, with a credit note); the order carries its refunds and refunded_total. A full refund also cancels the order, so order.cancelled is sent too; don't rely on the order of the two events.

User and preference events

These events are about the user rather than your app's orders. They are opt-in: select them explicitly for your endpoint, * doesn't include them.

Type	Constant	Sent to	data
user.updated	EventType::USER_UPDATED	apps the user is connected to (untrusted apps only with a token of the user carrying user, user:read or *), the app that made the change included	object: the full profile {object: "user", id, name, username, email, email_verified, avatar, version}; changed: the changed fields, e.g. ["name", "avatar"] (never old values)
user.deleted	EventType::USER_DELETED	apps the user was connected to	object: {object: "user", id, deleted: true, deleted_at}
preference.updated	EventType::PREFERENCE_UPDATED	trusted apps that may read the namespace, never the app that made the change	object: {object: "preference", user_id, namespace, key, version, deleted, updated_at, updated_by: {type: "user"|"app", client_id}}, never the value

{"id": "01JEVT…", "type": "user.updated", "created": 1762500000,
  "data": {"object": {"object": "user", "id": "01JUSER…", "name": "Erika Mustermann", "username": "erika",
    "email": "erika@example.com", "email_verified": true,
    "avatar": "https://id.anikeen.com/avatars/01JUSER…", "version": 8},
  "changed": ["name", "avatar"]}}

• user.updated is sent for changes to name, username, the verified email address, email_verified and the profile picture, from any source (the user's settings, the profile API, support). A new email address arrives only once it is verified: email is null while the address isn't, and a requested change sends nothing until the user confirms it (then changed is ["email", "email_verified"] or ["email"]). avatar is a stable URL; avatar in changed means the picture behind it changed: drop a cached copy. new User($object) (Anikeen\Id\Resources\User) reads the object.
• Versions: version grows with every such change (profile_version in the REST shapes). Events can arrive late or out of order: keep the highest version you have seen and ignore older ones. A missed event can be caught up with findUserById().
• user.deleted is final and sent once: delete or anonymise your copy of the account (and what you keep only for it), and stop acting for the user. No other event about the user follows it, also none still queued. If a user.updated arrives later for the same ID, support restored the account: treat it as a returning user.
• preference.updated is thin: fetch the preference again (preferenceByUserId()) or drop your copy when deleted is true, and ignore events with a lower version than the one you hold (versions are per user). Nothing is sent for a write that changes nothing, and none when the account is deleted (user.deleted covers that).

use Anikeen\Id\Resources\User;

$object = $event['data']['object'];

if ($event['type'] === EventType::USER_UPDATED) {
    $profile = new User($object);
    $account = Account::firstWhere('anikeen_id', $profile->id());

    if ($account && $profile->version() > $account->profile_version) {
        $account->update([
            'name' => $profile->name(),
            'email' => $profile->email() ?? $account->email, // null while unverified
            'profile_version' => $profile->version(),
        ]);
    }
}

if ($event['type'] === EventType::USER_DELETED) {
    Account::firstWhere('anikeen_id', $object['id'])?->anonymise();
}

if ($event['type'] === EventType::PREFERENCE_UPDATED) {
    Cache::forget("preferences:{$object['user_id']}");
}

Errors

Every failed request throws Anikeen\Id\Exceptions\ApiException, with the user's token as well as with the app's (app*()). It carries:

• status: the HTTP status (also getCode()), 0 when Anikeen ID could not be reached,
• error: a stable error code when Anikeen ID sent one (e.g. billing_address_missing, already_cancelled), otherwise null,
• getMessage(): Anikeen ID's reason,
• isNotFound() (404), isConflict() (409) and isTemporary() (no response, 429 or 5xx: retry later),
• isBillingLimitReached() (409 billing_limit_reached: a charge would take the user's monthly bill above their billing limit),
• body(): the error response, for errors with details (e.g. remaining of billing_limit_reached).

Refused input (422) throws ValidationFailedException, a subclass of ApiException. Endpoints with codes per field (the profile API) fill errorCodes() (['username' => 'username_taken']), errorCodeFor($field) and hasErrorCode($code); errors() has the messages per field.

use Anikeen\Id\Exceptions\ApiException;

try {
    $order = $user->orders()->create($attributes);
} catch (ApiException $e) {
    if ($e->isTemporary()) {
        return back()->with('error', 'Anikeen ID is not reachable right now, please try again.');
    }

    report($e);

    return back()->with('error', $e->getMessage());
}

Failed lists ($user->invoices(), …) throw CollectionException, a subclass of ApiException. ConfirmationRequiredException (a third-party app called checkout(), see above) stays its own type. All of them extend ResourceException, so existing catch (ResourceException $e) blocks keep working.

Testing

Develop against staging (ANIKEEN_ID_MODE=staging) with an OAuth client registered there. Payments on staging run in Stripe's test mode: pay with Stripe's test cards, e.g. 4242 4242 4242 4242 with any future expiry date and any CVC. No money is charged. Point ANIKEEN_ID_BASE_URL at your own Anikeen ID instance if you run one locally.

In unit tests, swap the HTTP client for a Guzzle MockHandler:

$mock = new \GuzzleHttp\Handler\MockHandler([
    new \GuzzleHttp\Psr7\Response(201, ['Content-Type' => 'application/json'], json_encode(['data' => ['id' => '01JORDER', 'status' => 'draft']])),
]);

$this->app->instance(AnikeenId::class, (new AnikeenId())->setHttpClient(new \GuzzleHttp\Client([
    'handler' => \GuzzleHttp\HandlerStack::create($mock),
    'base_uri' => 'https://id.test/api/',
])));

Trusted apps

Apps operated by Anikeen can be marked as trusted. They can charge without asking the user and use their own token (client credentials), so billing keeps working when the user's login expired.

App subscriptions (trusted apps, no user token)

subscriptions() acts with the user's own access token and stops working when the user's login expired. Trusted apps can manage a user's subscriptions with the app's own token (client credentials, scope subscriptions:client) instead:

$subscriptions = $team->owner->appSubscriptions(); // nothing is requested yet

$subscription = $subscriptions->create([
    'group' => $team->id,
    'name' => 'Cloud Server S',
    'unit' => 'hour',
    'price' => 0.0137,
    'idempotency_key' => "server:{$pendingServer->id}", // retries return the same subscription
]);

$subscription->checkout();             // bill the first period
$subscription->checkout(startsAt: $domain->registered_at); // already running: bill the period that started then
$subscription->checkout(                // running for longer: also bill the periods that have ended
    startsAt: $domain->registered_at,
    billElapsedPeriods: true,
    maxNetAmount: '15.57',             // net ceiling, e.g. the amount the customer agreed to
);
$subscription->pause();                // expires when the paid period ends
$subscription->resume();               // expired subscriptions start a new period
$subscription->revoke(refund: false);  // cancel

$subscriptions->find($id);             // null if unknown or not this user's
$subscriptions->all(['group' => $team->id, 'active' => true]);

The user's Anikeen ID is read from the billable's anikeen_id attribute (AnikeenId::useUserIdField('…') to change it). The app must be trusted by Anikeen ID; it sees the subscriptions it created (plus those of clients delegated to it).

Starting from an earlier date

checkout(startsAt: …) books a service that is already running, e.g. a domain registered before the customer came to your app. If the first period from that date is still running, it is billed now and renews when it ends. An older start is refused with period_already_ended, unless you pass billElapsedPeriods: true with maxNetAmount (net, up to two decimals; both together, or checkout() throws an InvalidArgumentException without sending anything):

• every period that has ended plus the running one is billed now, as one line with the full service period. It lands on the user's collective order of the current month and is invoiced and charged with the next monthly bill; nothing is back-dated.
• the start may be at most about three years ago (422 otherwise).
• if the periods come to more than maxNetAmount, nothing is booked: 409 elapsed_amount_exceeded, with the real amount in $e->body()->net_amount (e.g. "20.76"), so you can show it and retry.
• 409 elapsed_periods_not_allowed when the subscription can't be billed this way (e.g. it ran before, replaces another one, or is billed by the hour or day with a monthly cap).

try {
    $subscription->checkout(startsAt: $startsAt, billElapsedPeriods: true, maxNetAmount: $confirmed);
} catch (ApiException $e) {
    if ($e->error === 'elapsed_amount_exceeded') {
        $actual = $e->body()->net_amount; // ask again with the real amount
    } else {
        throw $e;
    }
}

Error codes

Failures throw Anikeen\Id\Exceptions\ApiException with status (0 = not reachable), a stable error code (already_active, already_cancelled, not_active, already_paused, already_resumed, billing_address_missing, not_changeable, subscription_not_found, idempotency_key_conflict, in_checkout_session, trial_already_used, proration_not_possible, credit_exceeds_bill, period_already_ended, elapsed_periods_not_allowed, elapsed_amount_exceeded), the error response via body() and isNotFound(), isConflict(), isTemporary():

try {
    $subscription->revoke();
} catch (ApiException $e) {
    if ($e->isNotFound() || $e->error === 'already_cancelled') {
        // already gone
    } elseif ($e->isTemporary()) {
        // retry later
    } else {
        throw $e;
    }
}

Confirmable orders (trusted apps)

Trusted apps can charge one-off orders right away ('checkout' => true). With 'confirm' => true the user confirms and pays the order on Anikeen ID instead, like for a third-party app – e.g. a top-up the user starts in your app: Anikeen ID shows the order with VAT, the billing address and the payment method (one can be added there) and takes the payment.

$order = app(AnikeenId::class)->createOrderForUser($team->owner->anikeen_id, [
    'group' => $team->id,
    'confirm' => true,
    'return_url' => route('billing.topup.done'),   // same origin as one of your redirect URIs
    'metadata' => ['topup' => $topup->id],          // returned as is, also in the order webhooks
    'items' => [['type' => 'digital', 'name' => 'Credit', 'unit' => 'onetime', 'units' => 1, 'gross_price' => '10.00']],
])->data;

return redirect()->away($order->confirmation_url);
// later: https://console.test/billing/topup/done?status=completed&order=01K…

confirm needs items and can't be combined with checkout or a transaction (422). The draft expires after 24 hours (expires_at): it is cancelled, confirmation_url becomes null and checkout() answers 409 confirmation_expired. Follow the order through its webhooks: order.created, then order.completed once paid (order.payment_failed for a declined charge) or order.cancelled when the user declines or it expires. return_url and metadata work for every order, also with the user's token ($user->orders()->create([...])).

Changing running subscriptions (trusted apps)

update() changes a subscription before its checkout (afterwards only the description). change() changes price, unit, name, description or discount of a running subscription, like a plan change (send only what changes):

use Anikeen\Id\Resources\AppSubscription;

// upgrade now, prorated: the unused rest of the period is credited, the new price charged for it
$subscription->change(['apply' => AppSubscription::APPLY_NOW, 'price' => '0.0274', 'name' => 'Cloud Server M']);

// downgrade from the next period on
$subscription->change(['apply' => AppSubscription::APPLY_PERIOD_END, 'price' => '4.99']);
$subscription->scheduled_change;       // {applies_at, name, description, unit, price, discount, created_at}
$subscription->cancelScheduledChange(); // keep the current values after all

• now credits the unused part of the current period at the rate it was billed at and charges the rest at the new price, both on the user's open bill. A new unit starts a new, fully billed period now. A downgrade whose credit would exceed the open bill is refused with 409 credit_exceeds_bill: schedule it for the period end instead. 409 proration_not_possible when the current period wasn't billed to the subscription (e.g. a takeover); period_end works.
• period_end changes nothing now; the next period is billed at the new values. A new period_end change replaces the scheduled one, now drops it.
• During a free trial nothing was billed: both just change what the trial ends in.
• discount replaces the discount from the next billed period on, null ends it. When the unit changes, a discount that counts in periods or an amount_off has to be sent again (422).
• Subscriptions with a monthly cap change only with period_end.
• Only running subscriptions can change: 409 not_changeable for drafts (use update()), paused, cancelling, expired and cancelled ones.

When a change takes effect (right away or at the period end), Anikeen ID sends subscription.updated (EventType::SUBSCRIPTION_UPDATED) with the old values of the changed fields in $event['data']['previous_attributes']. Telling the user about a price increase (and getting consent where needed) is up to your app.

App orders (trusted apps, no user token)

Orders that bill the app's subscriptions, read with the app's token (scope orders:client):

$team->owner->appOrders()->pending();         // unpaid orders of one user, oldest first
app(AnikeenId::class)->appOrders()->pending(); // of all users
$team->owner->appOrders()->find($orderId);     // null if unknown or not this user's

Each order has status (processing = current month, still collecting; pending = closed and not paid; completed; cancelled), the totals, payment_attempts, next_payment_attempt_at (null = no more automatic retries) and last_payment_error.

Collective (monthly) orders are kept per app: your subscriptions are never billed on the same order as another app's, even if both use the same group (or none); clients delegated to your app bill on your app's orders. $order->oauth_client_id is the app that bills the order.

Orders also list their lines and their invoice, e.g. to show a team's invoices or to attribute amounts (commissions) per subscription:

$order = app(AnikeenId::class)->appOrders()->find($orderId);

foreach ($order->items as $item) {
    $item->subscription_id;                     // null for lines that bill no subscription
    $item->period_start; $item->period_end;     // ISO 8601, the end is exclusive; null without a period
    $item->net_amount;                          // units × price, rounded to cents
    $item->discount;                            // {label, percent_off, amount_off} on a discount line, else null
}

$order->invoice;                                // null until paid, then {id, number, status, …, pdf_url}
$pdf = app(AnikeenId::class)->appOrders()->invoicePdf($orderId); // the invoice PDF (binary)

The net amount actually billed for a subscription is the sum of net_amount of its lines (discount lines are negative). invoicePdf() throws ApiException with 404 invoice_not_found before the order is paid and 409 invoice_not_ready while the PDF is still being rendered (usually seconds after the payment; try again later). Legacy orders from before collective orders were kept per app (oauth_client_id null) can also bill other apps' subscriptions: there items lists only your lines (the totals are the whole order's), invoice->pdf_url is null and invoicePdf() throws ApiException with 403 invoice_includes_other_apps.

Billing portal links (trusted apps)

A "Manage billing" button for a user whose token your app doesn't have (e.g. the owner of a team your app bills): create a link to the user's billing pages on Anikeen ID with the app's token (scope subscriptions:client or orders:client). Like Stripe's customer portal, it works without a login:

Route::post('teams/{team}/billing', function (Team $team) {
    return redirect()->away($team->owner->appBillingPortalUrl([
        'return_url' => route('teams.show', $team), // "Back to <app>"; same origin as one of your redirect URIs
        'group' => $team->id,                       // only this group's subscriptions, orders and invoices
        'flow' => 'invoices',                       // overview (default), payment_method, payment_method_update,
                                                    // invoices, subscriptions or orders
    ]));
});

app(AnikeenId::class)->createBillingPortalLinkForUser($userId, ['flow' => 'payment_method_update']);
// {object: "billing_portal_link", url, user_id, flow, group, return_url, expires_at}

The link is single use and valid for about 15 minutes: create it when the user clicks and redirect right away; don't store, mail or reuse it (a second request with the same link, e.g. a reload, gets a 403). Opening it starts a portal session for that user that needs no login and signs nobody in: only the billing pages of the flow, only what bills your app's subscriptions (of the group), with "Back to app". The user's account settings, other apps and OAuth consent stay behind the normal login; signed in as another account, the portal still shows only the link's user. The session ends after an hour without activity or on "Back to app". payment_method_update leads straight to replacing the payment method (e.g. after a failed payment) and back to return_url. For the signed-in user with their own token, $user->billingPortalUrl() stays available.

Charges and billing limit (trusted apps)

Trusted apps can book single items onto a user's open monthly bill of the app, e.g. each item a shipping app sends: one line per charge, no subscription, charged with the bill on the 1st like every other line (invoice and VAT by Anikeen ID). Anikeen has to enable charging for your app and sets a maximum per charge; the user must be connected to your app (they authorised it, or your app bills them through subscriptions or orders).

$anikeen = app(AnikeenId::class);

$charge = $anikeen->createChargeForUser($user->anikeen_id, [
    'idempotency_key' => "shipment-{$shipment->id}", // per app and user: a retry returns the same charge
    'name' => 'Signed card',                         // the line on the bill
    'type' => 'physical',                            // digital (default), physical, physical-reduced
    'quantity' => 2,
    'unit_price' => '4.00',                          // net per piece, up to 6 decimals
    'reference' => "order-{$shipment->order_id}",    // your own id; not on the bill
    // 'group' => $team->id,                         // only a group your app already bills the user in
    // 'occurred_at' => '2026-11-05T14:00:00Z',      // the service date, at most 31 days ago
]);

$charge->id();          // keep it to void the charge later
$charge->grossAmount(); // "9.52": what it added to the bill
$charge->orderId();     // the monthly bill it is on
$charge->status();      // open, billed (the bill was closed) or voided

$anikeen->findChargeForUser($user->anikeen_id, $chargeId);
$anikeen->voidChargeForUser($user->anikeen_id, $chargeId, 'Parcel lost'); // while the bill is open

• Idempotency: retrying with the same key and the same fields returns the existing charge (200 instead of 201), also after the limit was reached; the same key with other fields is 409 idempotency_key_conflict (charge_id in body()). Use one key per item you charge for.
• Voiding removes the line while the bill is open (an already voided charge is returned as it is). Once the bill was closed: 409 charge_already_billed; only a refund of the order by Anikeen credits it.
• group is null or a group your app already bills the user in (a running subscription or an open monthly bill of your app); others are refused with 409 group_not_allowed.
• reference and metadata (up to 20 string values) are your data about the user, kept with the charge and not shown on the bill: put nothing sensitive there.

Billing limit. A user can set one monthly limit (gross) for their whole open monthly bill across all Anikeen services. A charge that would take the bill above it is refused with 409 billing_limit_reached; exactly reaching the limit is allowed, 0.00 refuses every charge. Subscription renewals and usage are still billed, so the bill can end above the limit. Read the limit to stop offering paid actions early (advisory only, it reserves nothing):

$limit = $anikeen->billingLimitForUser($user->anikeen_id);

$limit->hasLimit();     // false: no limit, every charge fits
$limit->isReached();    // used >= limit: start no new paid service
$limit->remaining();    // "17.60" gross room left, null without a limit
$limit->remainingNet(); // "14.78" at the user's VAT rate, a hint
$limit->allows('9.52'); // would this charge fit right now (advisory)
$limit->resetsAt();     // when this month's bills are closed
$limit->version();      // only goes up
$limit->used();         // the user's open bills across all Anikeen services, null without a limit
$limit->usedByApp();    // your app's share; used − usedByApp = "your other Anikeen services"

used (the user's open bills across all Anikeen services) is visible to apps only while the user has set a limit; without one limit, used, remaining and remaining_net are null. usedByApp() (your app's own open bills) is always there. The user sees their own limit in $user->billingOverview()->billing_limit (with used, without used_by_app; null while they can't set one). Apps that may charge can read the limit; others need Anikeen to allow it (403 billing_limit_not_enabled).

Handling a refused charge:

use Anikeen\Id\Exceptions\ApiException;

try {
    $charge = $anikeen->createChargeForUser($user->anikeen_id, $attributes);
} catch (ApiException $e) {
    if ($e->isBillingLimitReached()) {
        $e->body()->remaining;  // room left before this charge, e.g. "2.60"
        $e->body()->required;   // the refused charge, gross
        $e->body()->resets_at;  // when the limit has room again at the latest
        return $shipment->holdForBillingLimit();
    }

    match ($e->error) {
        'charge_exceeds_maximum' => report($e),   // above your app's maximum ($e->body()->max_charge_net)
        'group_not_allowed' => report($e),
        'billing_address_missing' => $shipment->askForBillingAddress(),
        default => throw $e,
    };
}

Webhooks. billing_limit.reached and billing_limit.available are sent when the limit is reached or has room again (a raised or removed limit, a void, the monthly reset). They are opt-in (select them for your endpoint; * doesn't include them) and go only to apps that may read the limit of a user connected to them. data.object is the billing limit as your app reads it, data.reason says why (booking, limit_changed, limit_removed, voided, period_reset, order_changed). Keep the highest version per user and ignore events with a lower or equal one, so a late delivery can't undo a newer state. In the match of the webhook route:

EventType::BILLING_LIMIT_REACHED, EventType::BILLING_LIMIT_AVAILABLE => Customer::syncBillingLimit(
    $object['user_id'], reached: $event['type'] === EventType::BILLING_LIMIT_REACHED, version: $object['version'],
),

The limit is checked live when a charge is booked, so a late or missed webhook never lets a charge through; poll billingLimitForUser() if you need the current state.

Error codes

Status	error
403	client_not_allowed (not a trusted app with its own token), charges_not_enabled (charging is not enabled for your app; also for reads and voids), billing_limit_not_enabled (limit read only)
404	user_not_found (unknown, deleted or not connected to your app), charge_not_found
409	billing_limit_reached (isBillingLimitReached()), charge_exceeds_maximum (+ max_charge_net), group_not_allowed, idempotency_key_conflict (+ charge_id), billing_address_missing, charge_already_billed (+ charge_id)
422	validation (errors), no error code
429	too_many_requests (isTemporary())

Checkout sessions (the user confirms several subscriptions at once)

Instead of checking subscriptions out itself, an app can let the user confirm them on Anikeen ID, all of them in one step: a checkout session bundles new subscriptions (or existing drafts of the app, ['id' => …]) of one user. The user sees every item with its price and the total of the first period, confirms (all subscriptions start, or none) or cancels, and returns to return_url. Open sessions expire after 24 hours with their drafts. Trusted apps can still check out directly; sessions are opt-in.

Example: a cart with several products and coupon prices:

use Anikeen\Id\Exceptions\ApiException;

$session = $request->user()->appCheckoutSessions()->create([   // app token; or ->checkoutSessions() with the user's token
    'return_url' => route('builder.done'),                      // same origin as one of your redirect URIs
    'metadata' => ['cart' => $cart->id],                        // returned as is
    'idempotency_key' => "cart:{$cart->id}",                    // retries return the same session
    'subscriptions' => $cart->items->map(fn ($item) => [
        'group' => $team->id,
        'name' => $item->product->name,
        'description' => $item->label,
        'unit' => $item->unit,                                  // hour, day, week, month, year
        'price' => $item->priceAfterCoupon(),                   // net, per unit
        'payload' => ['cart_item' => $item->id],
    ])->all(),
]);

$cart->update(['checkout_session_id' => $session->id, 'subscription_ids' => $session->subscriptionIds()]);

return redirect($session->confirmationUrl());
// later: https://console.test/builder/done?status=completed&checkout_session=01K…

Provision when the webhook arrives (or after checking the session through the API; never trust the query string):

use Anikeen\Id\Webhooks\EventType;

match ($event['type']) {
    EventType::CHECKOUT_COMPLETED => Provisioner::provision($event['data']['object']['subscriptions']), // all running
    EventType::CHECKOUT_CANCELLED, EventType::CHECKOUT_EXPIRED => Cart::release($event['data']['object']['metadata']['cart'] ?? null),
    default => null,
};

app(AnikeenId::class)->appCheckoutSessions()->find($id)?->isCompleted(); // any user's session
$session->refresh()->subscriptions();  // AppSubscription objects
$session->cancel();                    // withdraw an open session and its drafts (e.g. the cart changed)

While a session is open, its subscriptions can't be checked out or repriced by the app (409 in_checkout_session / not_changeable). The session's status is open, completed, cancelled or expired (isOpen(), isCompleted(), isCancelled() for cancelled or expired). subscription.activated / subscription.cancelled are still sent per subscription, before the checkout.* event of the session.

User accounts (trusted apps, no user token)

Trusted apps can look up and create Anikeen ID accounts with the app's own token. Email addresses are matched regardless of case.

$anikeenId = app(AnikeenId::class);

$account = $anikeenId->findUserByEmail('erika@example.com'); // null if no account uses it
$account?->data->id;                   // also name, email, email_verified, has_billing_address

$result = $anikeenId->createUser([     // finds the account of the email address or creates it
    'name' => 'Erika Mustermann',
    'email' => 'erika@example.com',
    'send_invitation' => true,         // a new account gets a mail with a link to set a password
]);
$result->data->created;                // false: the account already existed (and is unchanged)
$result->data->invitation_sent;        // only for an account created by this call without a password

findUserByEmail() changes nothing. It throws ApiException when the request fails for any reason other than an unknown address.

User profiles

Changing the profile (user token)

With a token of the user carrying Scope::USER (user), your app can change the user's name, username, email address and profile picture. Each call returns the updated profile (Anikeen\Id\Resources\User) and clears the cached getUserData().

use Anikeen\Id\Exceptions\ValidationFailedException;

try {
    $profile = $user->updateProfile([          // only the fields sent change
        'name' => 'Erika Mustermann',
        'username' => 'erika',
        'email' => 'erika.new@example.com',
    ]);
} catch (ValidationFailedException $e) {
    return back()->withErrors(match ($e->errorCodeFor('username')) {
        'username_taken' => ['username' => 'This username is taken.'],
        default => $e->errors(),
    });
}

$profile->email();                  // still the current address
$profile->pendingEmail();           // "erika.new@example.com" until the user confirms it
$profile->pendingEmailExpiresAt();

$user->uploadAvatar($request->file('avatar'));                         // a path or a file
$user->uploadAvatar($path, ['x' => 120, 'y' => 40, 'size' => 512]);    // a square, in pixels
$user->removeAvatar();                                                  // back to the initials

• Email addresses never change right away. Anikeen ID mails a confirmation link to the new address and a notice to the current one; the new address becomes the user's address only once they confirm it, signed in to Anikeen ID. Until then the current one stays valid for sign-in and mails, and user.updated follows the confirmation. A new request replaces a pending one; a pending address is dropped after 7 days (pendingEmailExpiresAt()).
• Pictures: jpeg, png, webp or gif, at most 5 MB and 64 to 8000 pixels per side; without crop the centre is used. The avatar URL stays the same when the picture changes.
• Limits: 30 requests a minute per app and user, new email addresses 5 an hour and picture uploads 10 an hour per user (429 too_many_requests with Retry-After). Requests with an address that is taken count too.

Status	error
401	unauthenticated
403	missing_scope (no user scope), user_token_required (an app token: there is no user to change)
413	avatar_too_large (the upload is larger than the server accepts)
422	ValidationFailedException, codes per field: name_invalid, username_taken, username_invalid, email_taken, email_invalid, avatar_invalid, avatar_too_large, crop_invalid (keyed by crop.x, crop.y or crop.size; errorCodeFor('crop') finds it), else validation_failed
429	too_many_requests

Branch on the codes, the messages are for people and may change.

Reading a user by ID (trusted apps)

Trusted apps can read the profile of a user connected to them (a token of the user, a subscription or an order of the app) with the app's own token, e.g. to catch up on a missed user.updated:

$profile = app(AnikeenId::class)->findUserById($user->anikeen_id); // null: unknown, deleted or not connected

$profile?->name();
$profile?->email();          // returned even while unverified
$profile?->emailVerified();
$profile?->avatar();
$profile?->version();        // compare with the version of user.updated
$profile?->locale;           // also username, created_at

It throws ApiException for 403 client_not_allowed (not a trusted app), 429 too_many_requests and other failures. The profile carries no billing or account data; read those through their own endpoints.

Preferences

Anikeen ID keeps small per-user settings as JSON values under a namespace and a key, so they follow the user across devices and apps:

• global is shared by all apps. Only registered keys and values are accepted: today SharedPreference::APPEARANCE with Appearance::SYSTEM, LIGHT or DARK.
• App namespaces (e.g. acme) hold one app's own data: onboarding state, a default workspace, the user's customer ID at a payment provider. Use another namespace on staging (e.g. acme-staging), so test data never mixes with production.

Registration. Access never comes from scopes alone: any client can request any scope. Ask Anikeen to register your OAuth client(s) (the app has to be trusted) for

• the namespaces your app owns (read, write and the lookup),
• read access to another app's namespace,
• global with the app's token (users always read and write their own global with their token),
• keys whose values are unique (see the lookup below).

Without it, app requests fail with 403 client_not_trusted or 404 namespace_not_found.

Scopes. User tokens need Scope::PREFERENCES (preferences, read and write) or Scope::PREFERENCES_READ (preferences:read); app tokens Scope::PREFERENCES_CLIENT (preferences:client).

Limits. A value is at most 2048 bytes of JSON and 4 levels deep; at most 50 keys per user and namespace (updating a key always works); keys match ^[a-z][a-z0-9_]{0,63}$. Per minute: 60 requests per user and app with user tokens, 600 per app with the app token and 120 lookups per app (429 rate_limited with Retry-After).

Not a secrets store. Values are stored as plain JSON and shown to Anikeen's support and to the user on a request for their data. Store IDs and settings, never passwords, API keys or tokens: keys that look like credentials (secret, token, password, api_key, …) are rejected with 422 forbidden_key.

The user's shared preferences (user token)

use Anikeen\Id\Enums\Appearance;
use Anikeen\Id\Enums\SharedPreference;

$user->globalPreference(SharedPreference::APPEARANCE, Appearance::SYSTEM); // the default when not set
$user->globalPreferences()->values();     // ['appearance' => 'dark']

$preference = $user->setGlobalPreference(SharedPreference::APPEARANCE, Appearance::DARK);
$preference->version;                     // e.g. 1042

$user->deleteGlobalPreference(SharedPreference::APPEARANCE);

User tokens reach global only; an app namespace answers 404 namespace_not_found, whatever the token's scopes. The app's own token (client credentials) has no user and gets 401 on these routes.

Preferences of any user (trusted apps)

With the app's own token, by the user's Anikeen ID:

$anikeenId = app(AnikeenId::class);

$preferences = $anikeenId->preferencesByUserId($userId, 'acme'); // sorted by key, no pagination
$preferences->get('onboarding', []);     // the value or a default; also has(), find(), values()

$preference = $anikeenId->preferenceByUserId($userId, 'acme', 'onboarding'); // 404 preference_not_found if not set
$preference->value;                      // JSON objects as stdClass, so {} stays {}
$preference->version;
$preference->updated_by;                 // {type: "user"|"app", client_id}

$anikeenId->setPreferenceByUserId($userId, 'acme', 'onboarding', ['step' => 3]);
$anikeenId->deletePreferenceByUserId($userId, 'acme', 'onboarding');

A value is any JSON value; pass (object) [] for an empty object ([] is an empty list). setPreferenceByUserId() returns the stored preference; wasCreated() tells whether the write created the key. A deleted user's preferences are gone: every call answers 404 user_not_found.

Conditional writes and retries

Writes are last write wins by default. Every write gives the preference a new version. Versions are opaque: they only go up (also when a key is deleted and set again) and increase per user, not by one per key. Pass the version you read to write only if nobody changed it in between (If-Match), or createOnly to write only if the key isn't set yet (If-None-Match: *):

use Anikeen\Id\Exceptions\PreconditionFailedException;

$preference = $anikeenId->preferenceByUserId($userId, 'acme', 'layout');

try {
    $anikeenId->setPreferenceByUserId($userId, 'acme', 'layout', $merged, ifVersion: $preference->version);
} catch (PreconditionFailedException $e) {
    $e->error;            // "preference_version_mismatch" (or "preference_exists" for createOnly)
    $e->currentVersion(); // the version stored now, null when the key isn't set: reload, merge, retry
}

$anikeenId->setPreferenceByUserId($userId, 'acme', 'welcome_sent_at', now()->toIso8601String(), createOnly: true);

deletePreferenceByUserId(), setGlobalPreference() and deleteGlobalPreference() take ifVersion too. Writing the value that is already stored is a no-op that succeeds (no new version), even when the precondition would fail, so retrying a write after a timeout is safe.

Unique keys and the lookup

Anikeen can declare keys of your namespace unique, e.g. customer_id. Their values are strings of 1 to 255 characters without surrounding whitespace, held by at most one user: setting another user's value fails with 409 preference_value_taken. Your app can then find the user by value, e.g. in a payment provider's webhook:

$userId = $anikeenId->findUserIdByPreference('acme', 'customer_id', 'cus_123'); // null if nobody holds it

The value is sent in the body, never in the URL. findUserIdByPreference() returns null only for 404 preference_not_found (also when the user was deleted); everything else throws, e.g. 422 key_not_unique for a key that isn't declared unique.

Error codes

Failures throw ApiException (412 PreconditionFailedException) with these error codes:

Status	error
401	unauthenticated (no or an invalid token; an app token on the user routes)
403	missing_scope, app_token_required (a user token on the app routes), client_not_trusted, namespace_read_only, lookup_not_allowed
404	namespace_not_found (unknown or not accessible), user_not_found (also deleted users), preference_not_found, not_found
405	method_not_allowed
409	preference_value_taken
412	preference_version_mismatch, preference_exists
422	invalid_key, forbidden_key, unknown_shared_key, value_required, value_too_large, value_too_deep, invalid_shared_value, invalid_unique_value, key_not_unique, preference_limit_exceeded
429	rate_limited

A null value is rejected with 422 value_required: delete the key instead.

Caching

Anikeen ID is the source of truth. globalPreferences() and globalPreference() cache the list on the model instance (one request per instance); setGlobalPreference() and deleteGlobalPreference() clear it. For a copy that outlives the request, keep a read cache: fill it at sign-in, write to Anikeen ID first and update the copy from the response, and let it expire after about an hour, since other apps and the user can change shared preferences too (trusted apps can select the preference.updated webhook to drop it sooner):

$appearance = Cache::remember("appearance:{$user->id}", now()->addHour(),
    fn () => $user->globalPreference(SharedPreference::APPEARANCE, Appearance::SYSTEM));

$user->setGlobalPreference(SharedPreference::APPEARANCE, $request->appearance);
Cache::put("appearance:{$user->id}", $request->appearance, now()->addHour());

API authentication

Use this when your own API accepts access tokens issued by Anikeen ID.

Registering Middleware

To call your API from your own frontend with the user's session, append the middleware to the web middleware group in your application's bootstrap/app.php file:

->withMiddleware(function (Middleware $middleware) {
    $middleware->web(append: [
        \Anikeen\Id\Http\Middleware\CreateFreshApiToken::class,
    ]);
})

Implementing Auth (API tokens)

The package registers an anikeen guard driver and an anikeen user provider. Reference them in config/auth.php:

'guards' => [
    'web' => [
        'driver' => 'session',
        'provider' => 'users',
    ],

    'api' => [
        'driver' => 'anikeen',
        'provider' => 'anikeen',
    ],
],

'providers' => [
    'users' => [
        'driver' => 'eloquent',
        'model' => App\Models\User::class,
    ],

    'anikeen' => [
        'driver' => 'anikeen',
        'model' => App\Models\User::class,
        'column' => 'anikeen_id', // optional, see below
    ],
],

The guard accepts Authorization: Bearer <access token> with an access token issued by Anikeen ID (personal access token or OAuth token, a JWT). It verifies the RS256 signature with Anikeen ID's public key and the time claims (exp, nbf, iat, 60 seconds leeway). The token's sub (the user's Anikeen ID) is looked up in the column anikeen_id of the user model: the provider's column, else services.anikeen.user_id_column, else AnikeenId::useUserIdField(). Tokens of unknown users, client credentials tokens (no sub), expired or forged tokens leave the request unauthenticated, so auth:api answers 401 {"message": "Unauthenticated."} to JSON requests.

The user model uses Anikeen\Id\HasAnikeenTokens; the token's scopes are then available:

$request->user()->anikeenTokenCan('user');               // has the scope (or `*`)
$request->user()->anikeenTokenCanAny(['user', 'user:read']);

or as middleware (403 without the scope):

use Anikeen\Id\Http\Middleware\CheckForAnyScope;
use Anikeen\Id\Http\Middleware\CheckScopes;

Route::middleware(['auth:api', CheckScopes::using('user')])->post(...);                    // all scopes
Route::middleware(['auth:api', CheckForAnyScope::using('user', 'user:read')])->get(...);  // any scope

Options in config/services.php (anikeen):

Key	Default
public_key	–	Anikeen ID's public key (PEM; \n escapes allowed)
public_key_path	–	path to that key; without both the key shipped for the mode is used
user_id_column	anikeen_id	column holding the user's Anikeen ID
verify_revocation	false	also ask Anikeen ID (GET v1/user) whether the token is still valid, so revoked tokens stop working before they expire; fails closed when Anikeen ID is unreachable
revocation_cache_ttl	300	seconds that answer is cached per token

The key is read once per process. In tests AnikeenId::actingAs($user, ['user']) signs in without a token.

General

Setters and Getters

$anikeenId = new Anikeen\Id\AnikeenId();

$anikeenId->setClientId('abc123');
$anikeenId->setClientSecret('abc456');
$anikeenId->setToken('abcdef123456');

$anikeenId = $anikeenId->withClientId('abc123');
$anikeenId = $anikeenId->withClientSecret('abc123');
$anikeenId = $anikeenId->withToken('abcdef123456');

Results and resources

Low-level methods on AnikeenId (e.g. getAuthedUser(), createOrderPreview(), refreshToken()) return a Result. Check it before you use it:

$result = $anikeenId->getAuthedUser();

if (!$result->success()) {
    die('Ooops: ' . $result->error());
}

$user = $result->shift(); // the object, or the first item of a list

Resource methods ($user->orders(), $anikeenId->sshKeysByUserId(), …) return objects and throw ApiException instead (see Errors).

Examples

Get User SSH Keys

Uses the app's own token (client credentials):

$sshKeys = app(Anikeen\Id\AnikeenId::class)->sshKeysByUserId($anikeenUserId);

foreach ($sshKeys->toArray() as $sshKey) {
    echo $sshKey->name;
}

OAuth Tokens

$anikeenId = new Anikeen\Id\AnikeenId();

$anikeenId->setToken('abcdef123456');

$user = $anikeenId->getAuthedUser()->shift();

$user = $anikeenId->withToken('uvwxyz456789')->getAuthedUser()->shift();

Facade

use Anikeen\Id\Facades\AnikeenId;

AnikeenId::withToken('abcdef123456')->getAuthedUser();

Documentation

AnikeenId

Oauth

public function retrievingToken(string $grantType, array $attributes): Result

ManagesPreferences

public function preferencesByUserId(string $userId, string $namespace): Preferences
public function preferenceByUserId(string $userId, string $namespace, string $key): Preference
public function setPreferenceByUserId(string $userId, string $namespace, string $key, mixed $value, ?int $ifVersion = null, bool $createOnly = false): Preference
public function deletePreferenceByUserId(string $userId, string $namespace, string $key, ?int $ifVersion = null): void
public function findUserIdByPreference(string $namespace, string $key, string $value): ?string

ManagesPricing

public function createOrderPreview(array $attributes = []): Result

ManagesProducts

public function products(): Result
public function boxes(): Result

ManagesShippingLabels

public function shippingLabels(array $parameters = []): Result
public function shippingLabel(string $id): Result
public function shippingLabelPdf(string $id): ?string
public function issueShippingLabel(array $attributes): Result
public function shipShippingLabel(array $hex): Result
public function shippingPriceList(): Result

ManagesUserBilling

public function appOrders(): AppOrders
public function appCheckoutSessions(): AppCheckoutSessions
public function createBillingPortalLinkForUser(string $userId, array $attributes = []): object
public function createOrderForUser(string $userId, array $attributes): Result
public function createTransactionForUser(string $userId, array $attributes): Result
public function createChargeForUser(string $userId, array $attributes): AppCharge
public function findChargeForUser(string $userId, string $chargeId): AppCharge
public function voidChargeForUser(string $userId, string $chargeId, ?string $reason = null): AppCharge
public function billingLimitForUser(string $userId): BillingLimit

ManagesSocialiteUsers

public function socialiteUsers(): SocialiteUsers

ManagesSshKeys

public function sshKeysByUserId(string $userId): SshKeys

ManagesUsers

public function getAuthedUser(): Result
public function createUser(array $attributes): Result
public function findUserByEmail(string $email): ?Result
public function findUserById(string $userId): ?User
public function findOrCreateSocialiteUser(string $provider, string $providerId, ?string $email = null, ?string $name = null): Result
public function refreshToken(string $storedRefreshToken, string $scope = ''): Result
public function isEmailExisting(string $email): Result
public function setParent(mixed $parent): self
public function getParent()

Billable

ManagesAddresses

public function addresses(): Addresses
public function hasDefaultBillingAddress(): bool
public function setBillable(Billable|Model $billable): self
public function getBillable(): Billable

ManagesBalance

public function balance(): float
public function charges(): float
public function billingOverview(): object
public function charge(string|float $amount, string $paymentMethodId, array $options = []): Transaction
public function setBillable(Billable|Model $billable): self
public function getBillable(): Billable

ManagesCountries

public function countries(): Countries
public function setBillable(Billable|Model $billable): self
public function getBillable(): Billable

ManagesInvoices

public function invoices(array $parameters = []): Invoices
public function setBillable(Billable|Model $billable): self
public function getBillable(): Billable

ManagesOrders

public function orders(array $parameters = []): Orders
public function setBillable(Billable|Model $billable): self
public function getBillable(): Billable

ManagesPaymentMethods

public function paymentMethods(): PaymentMethods
public function hasPaymentMethod(): ?PaymentMethod
public function defaultPaymentMethod(): ?PaymentMethod
public function hasDefaultPaymentMethod(): bool
public function setDefaultPaymentMethod(string $id): PaymentMethod
public function billingPortalUrl(?string $returnUrl = null, array $options = []): string
public function createSetupIntent(array $options = []): Result
public function setBillable(Billable|Model $billable): self
public function getBillable(): Billable

ManagesProfile

public function profilePortalUrl(?string $returnUrl = null, array $options = []): string
public function updateProfile(array $attributes): User
public function uploadAvatar(SplFileInfo|string $file, ?array $crop = null): User
public function removeAvatar(): User
public function setBillable(Billable|Model $billable): self
public function getBillable(): Billable

ManagesSubscriptions

public function subscriptions(): Subscriptions
public function appSubscriptions(): AppSubscriptions
public function appCheckoutSessions(): AppCheckoutSessions
public function checkoutSessions(): CheckoutSessions
public function appOrders(): AppOrders
public function appBillingPortalUrl(array $attributes = []): string
public function setBillable(Billable|Model $billable): self
public function getBillable(): Billable

ManagesTaxation

public function vatRate(): float
public function setBillable(Billable|Model $billable): self
public function getBillable(): Billable

ManagesTransactions

public function transactions(): Transactions
public function setBillable(Billable|Model $billable): self
public function getBillable(): Billable

ManagesUserPreferences

public function globalPreferences(): Preferences
public function globalPreference(string $key, mixed $default = null): mixed
public function setGlobalPreference(string $key, mixed $value, ?int $ifVersion = null): Preference
public function deleteGlobalPreference(string $key, ?int $ifVersion = null): void

ManagesUserSshKeys

public function sshKeys(): SshKeys
public function setBillable(Billable|Model $billable): self
public function getBillable(): Billable

OAuth Scopes Enums

Development

Run Tests

composer test

Generate Documentation

composer docs