PersonalAccessTokens

Type

Class

Namespace

craft\services

Inherits

craft\services\PersonalAccessTokens » yii\base\Component » yii\base\BaseObject

Implements

yii\base\Configurable

Since

5.12.0

Personal access tokens, which users create from My Account → Tokens for apps and scripts that can’t complete an OAuth authorization flow.

An instance of the service is available via Craft::$app->getPersonalAccessTokens().

Tokens are OAuth personal access tokens, as in Laravel Passport. APIs offer their OAuth scopes for them by registering a craft\oauth\ScopeGroup, and the Tokens screen is only shown to users who may grant at least one registered scope:

use craft\oauth\ScopeGroup;

Craft::$app->getPersonalAccessTokens()->registerScopeGroup('my-plugin', fn() => new ScopeGroup(
    handle: 'my-plugin',
    label: 'My Plugin',
    scopes: ['my-plugin:read' => 'Read my plugin’s data'],
));

The scopes must be defined by a registered OAuth resource.

View source

Public Properties

Property	Description
behaviors	\yii\base\Behavior<static>[] – List of behaviors attached to this component.

Public Methods

Method	Description
__call()	Calls the named method which is not a class method.
__clone()	This method is called after the object is created by cloning an existing one.
__construct()	Constructor.
__get()	Returns the value of a component property.
__isset()	Checks if a property is set, i.e. defined and not null.
__set()	Sets the value of a component property.
__unset()	Sets a component property to be null.
attachBehavior()	Attaches a behavior to this component.
attachBehaviors()	Attaches a list of behaviors to the component.
behaviors()	Returns a list of behaviors that this component should behave as.
canGetProperty()	Returns a value indicating whether a property can be read.
canSetProperty()	Returns a value indicating whether a property can be set.
className()	Returns the fully qualified name of this class.
create()	Creates a personal access token, issued through the personal access client like Passport’s $user->createToken().
detachBehavior()	Detaches a behavior from the component.
detachBehaviors()	Detaches all behaviors from the component.
ensureBehaviors()	Makes sure that the behaviors declared in behaviors() are attached to this component.
getBehavior()	Returns the named behavior object.
getBehaviors()	Returns all behaviors attached to this component.
grants()	Returns the user’s active personal access tokens, and the apps they’ve authorized, for the registered scope groups.
hasEventHandlers()	Returns a value indicating whether there is any handler attached to the named event.
hasMethod()	Returns a value indicating whether a method is defined.
hasProperty()	Returns a value indicating whether a property is defined for this component.
init()	Initializes the object.
off()	Detaches an existing event handler from this component.
on()	Attaches an event handler to an event.
registerScopeGroup()	Registers a scope group.
rename()	Renames one of the user’s personal access tokens.
revoke()	Revokes one of the user’s personal access tokens, or if $tokenId is null, the access and refresh tokens they’ve granted an app for the registered scope groups.
scopeGroups()	Returns the registered scope groups, indexed by handle.
scopeGroupsFor()	Returns the scope groups the user may grant at least one scope from, indexed by handle.
trigger()	Triggers an event.

create()

Creates a personal access token, issued through the personal access client like Passport’s $user->createToken().

The scopes can come from several scope groups, so one token can access several APIs.

View source

Arguments

• $user
• $name
• $scopes (string[])
• $expiresIn

Returns

string – The access token. It isn’t stored, so it can’t be retrieved again.

Throws

• yii\base\InvalidArgumentException
  if the user may not grant the scopes

grants()

Returns the user’s active personal access tokens, and the apps they’ve authorized, for the registered scope groups.

Personal access tokens are listed individually, with their tokenId. Apps are listed once per client, with a tokenId of null, and stay listed while they can still refresh their access. Scopes are grouped by the handle of the scope group that defines them, and scopes outside the registered groups aren’t listed.

View source

Arguments

• $user

Returns

array{clientId: string, tokenId: string|null, name: string, scopes: array<string,string[]>, expiresAt: \DateTime, personal: bool}[]

init()

Initializes the object.

This method is invoked at the end of the constructor after the object is initialized with the given configuration.

View source

registerScopeGroup()

Registers a scope group.

View source

Arguments

• $handle (string)
• $factory (Closure) – Returns the craft\oauth\ScopeGroup with that handle, or null if it isn’t available.

rename()

Renames one of the user’s personal access tokens.

A token’s scopes are signed into it, so they can’t be changed after it’s created.

View source

Arguments

• $user
• $tokenId
• $name

Throws

• yii\base\InvalidArgumentException
  if the token isn’t one of the user’s active personal access tokens

revoke()

Revokes one of the user’s personal access tokens, or if $tokenId is null, the access and refresh tokens they’ve granted an app for the registered scope groups.

View source

Arguments

• $user
• $clientId
• $tokenId

scopeGroups()

Returns the registered scope groups, indexed by handle.

View source

Returns

array<string,\craft\oauth\ScopeGroup>

scopeGroupsFor()

Returns the scope groups the user may grant at least one scope from, indexed by handle.

View source

Arguments

• $user

Returns

array<string,\craft\oauth\ScopeGroup>