Module: WorkOS::Organizations

Extended by:
Client, Deprecation
Defined in:
lib/workos/organizations.rb

Overview

The Organizations module provides resource methods for working with Organizations

Class Method Summary collapse

Methods included from Deprecation

warn_deprecation

Methods included from Client

client, delete_request, execute_request, get_request, handle_error_response, post_request, put_request, user_agent

Class Method Details

.create_organization(domain_data: nil, domains: nil, name:, allow_profiles_outside_organization: nil, idempotency_key: nil) ⇒ Object

Create an organization

Parameters:

  • domain_data (Array<Hash>) (defaults to: nil) —

    List of domain hashes describing an organization domain.

  • name (String) —

    A unique, descriptive name for the organization

  • idempotency_key (String) (defaults to: nil) —

    An idempotency key

  • allow_profiles_outside_organization (Boolean, nil) (defaults to: nil) —

    Whether Connections within the Organization allow profiles that are outside of the Organization’s configured User Email Domains. Deprecated: If you need to allow sign-ins from any email domain, contact [email protected].

  • domains (Array<String>) (defaults to: nil) —

    List of domains that belong to the organization. Deprecated: Use domain_data instead.

Options Hash (domain_data:):

  • domain (String) —

    The domain that belongs to the organization.

  • state (String) —

    The state of the domain. “verified” or “pending”



84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/workos/organizations.rb', line 84

def create_organization(
  domain_data: nil,
  domains: nil,
  name:,
  allow_profiles_outside_organization: nil,
  idempotency_key: nil
)
  body = { name: name }
  body[:domain_data] = domain_data if domain_data

  if domains
    warn_deprecation '`domains` is deprecated. Use `domain_data` instead.'
    body[:domains] = domains
  end

  unless allow_profiles_outside_organization.nil?
    warn_deprecation '`allow_profiles_outside_organization` is deprecated. ' \
                     'If you need to allow sign-ins from any email domain, contact [email protected].'
    body[:allow_profiles_outside_organization] = allow_profiles_outside_organization
  end

  request = post_request(
    auth: true,
    body: body,
    path: '/organizations',
    idempotency_key: idempotency_key,
  )

  response = execute_request(request: request)
  check_and_raise_organization_error(response: response)

  WorkOS::Organization.new(response.body)
end

.delete_organization(id:) ⇒ Bool

Delete an Organization

Examples:

WorkOS::SSO.delete_organization(id: 'org_01EHZNVPK3SFK441A1RGBFSHRT')
=> true

Parameters:

  • id (String) —

    Organization unique identifier

Returns:

  • (Bool) —

    • returns ‘true` if successful



175
176
177
178
179
180
181
182
183
184
 
# File 'lib/workos/organizations.rb', line 175

def delete_organization(id:)
  request = delete_request(
    auth: true,
    path: "/organizations/#{id}",
  )

  response = execute_request(request: request)

  response.is_a? Net::HTTPSuccess
end

.get_organization(id:) ⇒ WorkOS::Organization

Get an Organization

Examples:

WorkOS::Portal.get_organization(id: 'org_02DRA1XNSJDZ19A31F183ECQW9')
=> #<WorkOS::Organization:0x00007fb6e4193d20
      @id="org_02DRA1XNSJDZ19A31F183ECQW9",
      @name="Foo Corp",
      @domains=
       [{:object=>"organization_domain",
         :id=>"org_domain_01E6PK9N3XMD8RHWF7S66380AR",
         :domain=>"foo-corp.com"}]>

Parameters:

  • id (String) —

    Organization unique identifier

Returns:



61
62
63
64
65
66
67
68
69
70
 
# File 'lib/workos/organizations.rb', line 61

def get_organization(id:)
  request = get_request(
    auth: true,
    path: "/organizations/#{id}",
  )

  response = execute_request(request: request)

  WorkOS::Organization.new(response.body)
end

.list_organization_roles(organization_id:) ⇒ Object

Retrieve a list of roles for the given organization.

Parameters:

  • organizationId (String) —

    The ID of the organization to fetch roles for.



189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
 
# File 'lib/workos/organizations.rb', line 189

def list_organization_roles(organization_id:)
  response = execute_request(
    request: get_request(
      path: "/organizations/#{organization_id}/roles",
      auth: true,
    ),
  )

  parsed_response = JSON.parse(response.body)

  roles = parsed_response['data'].map do |role|
    WorkOS::Role.new(role.to_json)
  end

  WorkOS::Types::ListStruct.new(
    data: roles,
    list_metadata: {
      after: nil,
      before: nil,
    },
  )
end

.list_organizations(options = {}) ⇒ Object

Retrieve a list of organizations that have connections configured within your WorkOS dashboard.

Parameters:

  • domains (Array<String>) —

    Filter organizations to only return those that are associated with the provided domains.

  • before (String) —

    A pagination argument used to request organizations before the provided Organization ID.

  • after (String) —

    A pagination argument used to request organizations after the provided Organization ID.

  • limit (Integer) —

    A pagination argument used to limit the number

  • order (String) —

    The order in which to paginate records of listed Organizations that are returned.



24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
 
# File 'lib/workos/organizations.rb', line 24

def list_organizations(options = {})
  options[:order] ||= 'desc'
  response = execute_request(
    request: get_request(
      path: '/organizations',
      auth: true,
      params: options,
    ),
  )

  parsed_response = JSON.parse(response.body)

  organizations = parsed_response['data'].map do |organization|
    ::WorkOS::Organization.new(organization.to_json)
  end

  WorkOS::Types::ListStruct.new(
    data: organizations,
    list_metadata: parsed_response['listMetadata'],
  )
end

.update_organization(organization:, stripe_customer_id: nil, domain_data: nil, domains: nil, name: nil, allow_profiles_outside_organization: nil) ⇒ Object

Update an organization

Parameters:

  • organization (String) —

    Organization unique identifier

  • domain_data (Array<Hash>) (defaults to: nil) —

    List of domain hashes describing an organization domain.

  • stripe_customer_id (String) (defaults to: nil) —

    The Stripe customer ID associated with this organization.

  • name (String) (defaults to: nil) —

    A unique, descriptive name for the organization

  • allow_profiles_outside_organization (Boolean, nil) (defaults to: nil) —

    Whether Connections within the Organization allow profiles that are outside of the Organization’s configured User Email Domains. Deprecated: If you need to allow sign-ins from any email domain, contact [email protected].

  • domains (Array<String>) (defaults to: nil) —

    List of domains that belong to the organization. Deprecated: Use domain_data instead.

Options Hash (domain_data:):

  • domain (String) —

    The domain that belongs to the organization.

  • state (String) —

    The state of the domain. “verified” or “pending”



131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
 
# File 'lib/workos/organizations.rb', line 131

def update_organization(
  organization:,
  stripe_customer_id: nil,
  domain_data: nil,
  domains: nil,
  name: nil,
  allow_profiles_outside_organization: nil
)
  body = { name: name }
  body[:domain_data] = domain_data if domain_data
  body[:stripe_customer_id] = stripe_customer_id if stripe_customer_id

  if domains
    warn_deprecation '`domains` is deprecated. Use `domain_data` instead.'
    body[:domains] = domains
  end

  unless allow_profiles_outside_organization.nil?
    warn_deprecation '`allow_profiles_outside_organization` is deprecated. ' \
                     'If you need to allow sign-ins from any email domain, contact [email protected].'
    body[:allow_profiles_outside_organization] = allow_profiles_outside_organization
  end

  request = put_request(
    auth: true,
    body: body,
    path: "/organizations/#{organization}",
  )

  response = execute_request(request: request)
  check_and_raise_organization_error(response: response)

  WorkOS::Organization.new(response.body)
end