SDKS

PHP SDK

The WorkOS PHP SDK provides your applications convenient access to the WorkOS SSO API.

Installation

To get started, install the WorkOS PHP SDK via Composer by running:

Terminal

file_copy
composer require workos/workos-php

View the source on GitHub.


Configuration

To use the SDK you must first provide your API key and Project ID from the Developer Dashboard:

PHP

file_copy
\WorkOS\WorkOS::setApiKey(getenv('WORKOS_API_KEY'));
\WorkOS\WorkOS::setProjectId(getenv('WORKOS_PROJECT_ID'));

SSO

The SSO Class provides convenient functions for interacting with the WorkOS SSO product.

SSO->getAuthorizationUrl($domain, $redirectUri, $state, $provider)

Generate an Authorization URL to intitiate the WorkOS OAuth 2.0 flow.

SSO->getAuthorizationUrl accepts the following arguments:

  • $domain null|string - Domain of the user that will be going through SSO
  • $redirectUri null|string - URI to direct the user to upon successful completion of SSO
  • $state null|array - Associative array containing state that will be returned from WorkOS as a JSON encoded string
  • $provider null|\WorkOS\Resource\ConnectionType - Service provider that handles the identity of the user

Returns:

  • string

Example:

app.php

file_copy
$url = (new \WorkOS\SSO())->getAuthorizationUrl(
  'my-co.com',
  {redirectURI},
  null,
  null
);

SSO->getProfile($code)

Fetch a \WorkOS\Resource\Profile for an authenticated user.

SSO->getProfile accepts the following arguments:

  • $code string - Code returned by WorkOS on completion of authorization flow

Returns:

  • \WorkOS\Resource\Profile

Example:

app.php

file_copy
$profile = (new WorkOSSSO())->getProfile($code)

SSO->createConnection($source)

Create a Connection.

SSO->createConnection accepts the following arguments:

  • $source string - Token returned by WorkOS as a result of the WorkOS.js embed workflow.

Returns:

  • \WorkOS\Resource\Connection

Example:

app.php

file_copy
$connection = $sso->createConnection($token);

AuditTrail

The AuditTrail Class provides convenient functions for accessing the WorkOS Audit Trail product.

AuditTrail->createEvent($event, $idempotencyKey)

Create an Audit Trail event.

AuditTrail->createEvent accepts the following arguments:

  • $event array - Array representing an Audit Trail event of the form:
    • $event["action_type"] string - Corresponding CRUD category of event. Can be one of C, R, U, or D.
    • $event["actor_name"] string - Display name of the entity performing the action.
    • $event["actor_id"] string - Unique identifier of the entity performing the action.
    • $event["group"] string - A single organization containing related members. This will normally be the customer of a vendor's application.
    • $event[l"ocation"] string - Identifier for where the event originated. This will be an IP address (IPv4 or IPv6), hostname, or device ID.
    • $event["occurred_at"] string - ISO-8601 datetime at which the event happened, with millisecond precision.
    • $event["metadata"] string - Arbitrary key-value data containing information associated with the event. Note: There is a limit of 50 keys. Key names can be up to 40 characters long, and values can be up to 500 characters long.
    • $event["target_id"] string - Unique identifier of the object or resource being acted upon.
    • $event["target_name"] string - Display name of the object or resource that is being acted upon.
  • $idempotencyKey string - Unique key guaranteeing idempotency of events for 24 hours.

Returns:

  • boolean

Example:

app.php

file_copy
$now = (new DateTime())->format(DateTime::ISO8601);

$event = [
    "group" => "organization_id",
    "action" => "user.login",
    "action_type" => "C",
    "actor_name" => "user@foo-corp.com",
    "actor_id" => "user_id",
    "target_name" => "user@foo-corp.com",
    "target_id" => "user_id",
    "location" =>  "1.1.1.1",
    "occurred_at" => $now,
];

(new WorkOSAuditTrail())->createEvent($event);

DirectorySync

The DirectorySync Class provides convenient functions for interacting with the WorkOS Directory Sync product.

DirectorySync->listDirectories($domain, $search, $limit, $before, $after)

List Directories.

DirectorySync->listDirectories accepts the following arguments:

  • $domain null|string - Domain of a Directory
  • $search null|string - Searchable text for a Directory
  • $limit int - Maximum number of records to return
  • $before null|string - Pagination cursor to receive records before a provided ID
  • $after null|string - Pagination cursor to receive records after a provided ID

Returns:

  • Array composed of the following:
    • Before cursor
    • After cursor
    • Array of \WorkOS\Resource\Directory

Example:

app.php

file_copy
list($before, $after, $directories) = (new WorkOSDirectorySync())->listDirectories();

DirectorySync->listGroups($directory, $user, $limit, $before, $after)

List Directory Groups.

DirectorySync->listGroups accepts the following arguments:

  • $directory null|string - Directory ID
  • $user null|string - Directory User ID
  • $limit int - Maximum number of records to return
  • $before null|string - Pagination cursor to receive records before a provided ID
  • $after null|string - Pagination cursor to receive records after a provided ID

Returns:

  • Array composed of the following:
    • Before cursor
    • After cursor
    • Array of \WorkOS\Resource\DirectoryGroup

Example:

app.php

file_copy
list($before, $after, $groups) = (new WorkOSDirectorySync())->listGroups();

DirectorySync->getGroup($directoryGroup)

Get a Directory Group.

DirectorySync->getGroup accepts the following arguments:

  • $directoryGroup string - Directory Group ID

Returns:

  • \WorkOS\Resource\DirectoryGroup

Example:

app.php

file_copy
$group = (new WorkOSDirectorySync())->getGroup("directory_grp_id");

DirectorySync->listUsers($directory, $group, $limit, $before, $after)

List Directory Users.

DirectorySync->listUsers accepts the following arguments:

  • $directory null|string - Directory ID
  • $group null|string - Directory Group ID
  • $limit int - Maximum number of records to return
  • $before null|string - Pagination cursor to receive records before a provided ID
  • $after null|string - Pagination cursor to receive records after a provided ID

Returns:

  • Array composed of the following:
    • Before cursor
    • After cursor
    • Array of \WorkOS\Resource\DirectoryUser

Example:

app.php

file_copy
list($before, $after, $users) = (new WorkOSDirectorySync())->listUsers();

DirectorySync->getUser($directoryUser)

Get a Directory User.

DirectorySync->getUser accepts the following arguments:

  • $directoryUser string - Directory User ID

Returns:

  • \WorkOS\Resource\DirectoryUser

Example:

app.php

file_copy
$user = (new WorkOSDirectorySync())->getUser("directory_user_id");

Resources

\WorkOS\Resource\Profile

An instance of \WorkOS\Resource\Profile will have attributes and values similar to the following:

JSON

file_copy
{
  "connectionType": "OktaSAML",
  "email": "user@{foo-corp.com}",
  "firstName": "User",
  "id": "prof_id",
  "idpId": "randomalphanum",
  "lastName": "Name"
}

\WorkOS\Resource\Connection

An instance of \WorkOS\Resource\Connection will have attributes and values similar to the following:

JSON

file_copy
{
  "id": "conn_id",
  "domains": [
    [
      "id": "conn_dom_id",
      "domain": "foo-corp.com"
    ]
  ],
  "status": "linked",
  "name": "Foo Corp Okta",
  "connectionType": "OktaSAML",
  "oauthUid": null,
  "oauthSecret": null,
  "oauthRedirectUri": "http://my-co.com/sso/provider/callback",
  "samlEntityId": null,
  "samlIdpUrl": null,
  "samlRelyingPartyTrustCert": null,
  "samlX509Certs": null
}

\WorkOS\Resource\Directory

An instance of \WorkOS\Resource\Directory will have attributes and values similar to the following:

JSON

file_copy
{
  "id": "directory_id",
  "externalKey": "external-key",
  "state": "linked",
  "type": "gsuite directory",
  "name": "user",
  "bearerToken": null,
  "projectId": "project_id",
  "domain": "foo-corp.com",
}

\WorkOS\Resource\DirectoryGroup

An instance of \WorkOS\Resource\DirectoryGroup will have attributes and values similar to the following:

JSON

file_copy
{
  "id": "directory_grp_id",
  "name": "Developers"
}

\WorkOS\Resource\DirectoryUser

An instance of \WorkOS\Resource\Directory will have attributes and values similar to the following:

JSON

file_copy
{
  "id": "directory_id",
  "externalKey": "external-key",
  "state": "linked",
  "type": "gsuite directory",
  "name": "user",
  "bearerToken": null,
  "projectId": "project_id",
  "domain": "foo-corp.com",
}