Linked Objects

Users have relationships to each other, like manager and subordinate or customer and sales representative. You can create users with relationships by using the Linked Objects API to represent the relationship.

  1. Create a Linked Object definition such as Manager:Subordinate or Case Worker:Client. These pairs are represented by a primary attribute and an associated attribute.
  2. Link users together to create the relationship between the two. You create a Linked Object value with a single request that links one primary and one associated user.

For each relationship:

  • A user has at most one primary link (a user has a single manager), but can have many associated links (a user can have many subordinates).
  • A user can be the primary in one relationship and the associated in another.
  • A user can be both the primary and associated in the same relationship.

Okta Expression Language function for Linked Objects provides access to the details about a linked user.

Note: The Linked Objects feature isn't available for OpenID Connect claims.

Example usage

Okta allows you to create up to 200 Linked Object definitions. These definitions are one-to-many, for example:

  • A manager has many subordinates. Each subordinate has one manager.
  • A sales representative has many customers. Each customer has one sales rep.
  • A case worker has many clients. Each client has one case worker.

Most organizations have more than one manager or sales representative. You can create the Linked Object definition once, and then assign the primary relationship to as many users as you have people in that relationship.

You can assign the associated relationship for a single primary user to as many users as needed. The associated user can be related to only one primary per Linked Object definition. But a user can be assigned to more than one Linked Object definition.

For example, assume that you've created one Linked Object definition for manager (primary) and for subordinates (associated):

  • Joe is Frank's manager.
  • Bob is Joe's manager, but Jane's subordinate.
  • Jane is the CEO, so she reports to herself.

Thus, you can create chains of relationships (Jane > Bob > Joe > Frank) or terminal relationships (Jane is both primary and associated user).

Then, if you create another Linked Object relationship for scrum team membership, you could assign relationships to the same four users:

  • Bob is the scrum lead for the Identity Scrum team.
  • Joe and Frank are both contributors to the team.

Bob can be the primary for a Manager:Subordinate, an associated user for that same Linked Object definition, and also the primary for the Scrumlead:Contributor Linked Object definition.

To represent a relationship, create a Linked Object definition that specifies a primary (parent) relationship and an associated (child) relationship, and then add a link in which the appropriate user is assigned to each side of that link type.

List all Linked Object Definitions
OAuth 2.0: okta.linkedObjects.read

Lists all Linked Object definitions

Responses
200

Success

403

Forbidden

429

Too Many Requests

get/api/v1/meta/schemas/user/linkedObjects
Request samples
Response samples
application/json
[]

Create a Linked Object Definition
OAuth 2.0: okta.linkedObjects.manage

Creates a Linked Object definition

Request
Request Body schema: application/json
required
object (LinkedObjectDetails)
name
required
string

API name of the primary or the associated link. The name parameter can't start with a number and can only contain the following characters: a-z, A-Z, 0-9, and _.

title
required
string

Display name of the primary or the associated link

type
required
string (LinkedObjectDetailsType)

The object type for this relationship

Value: Description
USER

Specifies the type of object

description
string

Description of the primary or the associated relationship

object (LinkedObjectDetails)
name
required
string

API name of the primary or the associated link. The name parameter can't start with a number and can only contain the following characters: a-z, A-Z, 0-9, and _.

title
required
string

Display name of the primary or the associated link

type
required
string (LinkedObjectDetailsType)

The object type for this relationship

Value: Description
USER

Specifies the type of object

description
string

Description of the primary or the associated relationship

object (LinkedObjectLinksSelf)

Specifies link relations (see Web Linking) available for the current status of an application using the JSON Hypertext Application Language specification. This object is used for dynamic discovery of related resources and lifecycle operations.

Responses
201

Created

400

Bad Request

403

Forbidden

409

Conflict

429

Too Many Requests

post/api/v1/meta/schemas/user/linkedObjects
Request samples
application/json
{
  • "primary": {
    • "name": "manager",
    • "title": "manager",
    • "description": "Manager link property",
    • "type": "USER"
    },
  • "associated": {
    • "name": "subordinate",
    • "title": "subordinate",
    • "description": "Subordinate link property",
    • "type": "USER"
    }
}
Response samples
application/json
{}

Retrieve a Linked Object Definition
OAuth 2.0: okta.linkedObjects.read

Retrieves a Linked Object definition

Request
path Parameters
linkedObjectName
required
string

Primary or Associated name

Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/meta/schemas/user/linkedObjects/{linkedObjectName}
Request samples
Response samples
application/json
{}

Delete a Linked Object Definition
OAuth 2.0: okta.linkedObjects.manage

Deletes the Linked Object definition specified by either the primary or associated name. The entire definition is removed, regardless of which name that you specify.

Request
path Parameters
linkedObjectName
required
string

Primary or Associated name

Responses
204

No Content

403

Forbidden

404

Not Found

429

Too Many Requests

delete/api/v1/meta/schemas/user/linkedObjects/{linkedObjectName}
Request samples
Response samples
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}