zyphr 0.1.37 → 0.1.39

data/docs/AuthUserDirectoryApi.md

@@ -0,0 +1,627 @@
+# Zyphr::AuthUserDirectoryApi
+
+All URIs are relative to *https://api.zyphr.dev/v1*
+
+| Method | HTTP request | Description |
+| ------ | ------------ | ----------- |
+| [**delete_end_user_by_application**](AuthUserDirectoryApi.md#delete_end_user_by_application) | **DELETE** /auth/users/{user_id} | Delete an end user (server-side admin) |
+| [**get_end_user_by_email**](AuthUserDirectoryApi.md#get_end_user_by_email) | **GET** /auth/users/by-email | Look up an end user by email (server-side admin) |
+| [**get_end_user_by_id**](AuthUserDirectoryApi.md#get_end_user_by_id) | **GET** /auth/users/{user_id} | Get an end user by id (server-side admin) |
+| [**get_end_user_claims**](AuthUserDirectoryApi.md#get_end_user_claims) | **GET** /auth/users/{user_id}/claims | Get an end user's stored custom claims (server-side admin) |
+| [**invite_end_user**](AuthUserDirectoryApi.md#invite_end_user) | **POST** /auth/users/invite | Pre-provision (invite) an end user (server-side admin) |
+| [**list_end_users**](AuthUserDirectoryApi.md#list_end_users) | **GET** /auth/users | List / search end users (server-side admin) |
+| [**set_end_user_claims**](AuthUserDirectoryApi.md#set_end_user_claims) | **PUT** /auth/users/{user_id}/claims | Set an end user's stored custom claims (server-side admin) |
+| [**update_end_user_by_application**](AuthUserDirectoryApi.md#update_end_user_by_application) | **PATCH** /auth/users/{user_id} | Update an end user (server-side admin) |
+
+
+## delete_end_user_by_application
+
+> delete_end_user_by_application(user_id)
+
+Delete an end user (server-side admin)
+
+Secret-key-scoped admin soft-delete for an arbitrary end user in the authenticating application. Works in both test and live environments. Scoped to the application via the application_id filter — a caller can never delete a user belonging to another application.  Mirrors the self-service `DELETE /auth/users/me` flow: revokes all sessions, soft-deletes the row (status='deleted'), and emits a `user.deleted` webhook with `method='application_admin'`. The audit log row survives (no FK to end_users), so org-history queries still resolve. 
+
+### Examples
+
+```ruby
+require 'time'
+require 'zyphr'
+# setup authorization
+Zyphr.configure do |config|
+  # Configure API key authorization: ApplicationSecret
+  config.api_key['X-Application-Secret'] = 'YOUR API KEY'
+  # Uncomment the following line to set a prefix for the API key, e.g. 'Bearer' (defaults to nil)
+  # config.api_key_prefix['X-Application-Secret'] = 'Bearer'
+
+  # Configure API key authorization: ApplicationPublicKey
+  config.api_key['X-Application-Key'] = 'YOUR API KEY'
+  # Uncomment the following line to set a prefix for the API key, e.g. 'Bearer' (defaults to nil)
+  # config.api_key_prefix['X-Application-Key'] = 'Bearer'
+end
+
+api_instance = Zyphr::AuthUserDirectoryApi.new
+user_id = '38400000-8cf0-11bd-b23e-10b96e4ef00d' # String | 
+
+begin
+  # Delete an end user (server-side admin)
+  api_instance.delete_end_user_by_application(user_id)
+rescue Zyphr::ApiError => e
+  puts "Error when calling AuthUserDirectoryApi->delete_end_user_by_application: #{e}"
+end
+```
+
+#### Using the delete_end_user_by_application_with_http_info variant
+
+This returns an Array which contains the response data (`nil` in this case), status code and headers.
+
+> <Array(nil, Integer, Hash)> delete_end_user_by_application_with_http_info(user_id)
+
+```ruby
+begin
+  # Delete an end user (server-side admin)
+  data, status_code, headers = api_instance.delete_end_user_by_application_with_http_info(user_id)
+  p status_code # => 2xx
+  p headers # => { ... }
+  p data # => nil
+rescue Zyphr::ApiError => e
+  puts "Error when calling AuthUserDirectoryApi->delete_end_user_by_application_with_http_info: #{e}"
+end
+```
+
+### Parameters
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **user_id** | **String** |  |  |
+
+### Return type
+
+nil (empty response body)
+
+### Authorization
+
+[ApplicationSecret](../README.md#ApplicationSecret), [ApplicationPublicKey](../README.md#ApplicationPublicKey)
+
+### HTTP request headers
+
+- **Content-Type**: Not defined
+- **Accept**: Not defined
+
+
+## get_end_user_by_email
+
+> get_end_user_by_email(email)
+
+Look up an end user by email (server-side admin)
+
+Secret-key-scoped lookup of a single end user by email address within the authenticating application. Scoped to the application — never resolves a user from another application. Does not return the password hash. 
+
+### Examples
+
+```ruby
+require 'time'
+require 'zyphr'
+# setup authorization
+Zyphr.configure do |config|
+  # Configure API key authorization: ApplicationSecret
+  config.api_key['X-Application-Secret'] = 'YOUR API KEY'
+  # Uncomment the following line to set a prefix for the API key, e.g. 'Bearer' (defaults to nil)
+  # config.api_key_prefix['X-Application-Secret'] = 'Bearer'
+
+  # Configure API key authorization: ApplicationPublicKey
+  config.api_key['X-Application-Key'] = 'YOUR API KEY'
+  # Uncomment the following line to set a prefix for the API key, e.g. 'Bearer' (defaults to nil)
+  # config.api_key_prefix['X-Application-Key'] = 'Bearer'
+end
+
+api_instance = Zyphr::AuthUserDirectoryApi.new
+email = 'email_example' # String | 
+
+begin
+  # Look up an end user by email (server-side admin)
+  api_instance.get_end_user_by_email(email)
+rescue Zyphr::ApiError => e
+  puts "Error when calling AuthUserDirectoryApi->get_end_user_by_email: #{e}"
+end
+```
+
+#### Using the get_end_user_by_email_with_http_info variant
+
+This returns an Array which contains the response data (`nil` in this case), status code and headers.
+
+> <Array(nil, Integer, Hash)> get_end_user_by_email_with_http_info(email)
+
+```ruby
+begin
+  # Look up an end user by email (server-side admin)
+  data, status_code, headers = api_instance.get_end_user_by_email_with_http_info(email)
+  p status_code # => 2xx
+  p headers # => { ... }
+  p data # => nil
+rescue Zyphr::ApiError => e
+  puts "Error when calling AuthUserDirectoryApi->get_end_user_by_email_with_http_info: #{e}"
+end
+```
+
+### Parameters
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **email** | **String** |  |  |
+
+### Return type
+
+nil (empty response body)
+
+### Authorization
+
+[ApplicationSecret](../README.md#ApplicationSecret), [ApplicationPublicKey](../README.md#ApplicationPublicKey)
+
+### HTTP request headers
+
+- **Content-Type**: Not defined
+- **Accept**: Not defined
+
+
+## get_end_user_by_id
+
+> get_end_user_by_id(user_id)
+
+Get an end user by id (server-side admin)
+
+Secret-key-scoped fetch of a single end user by id within the authenticating application. Scoped to the application — a caller can never read a user belonging to another application. 
+
+### Examples
+
+```ruby
+require 'time'
+require 'zyphr'
+# setup authorization
+Zyphr.configure do |config|
+  # Configure API key authorization: ApplicationSecret
+  config.api_key['X-Application-Secret'] = 'YOUR API KEY'
+  # Uncomment the following line to set a prefix for the API key, e.g. 'Bearer' (defaults to nil)
+  # config.api_key_prefix['X-Application-Secret'] = 'Bearer'
+
+  # Configure API key authorization: ApplicationPublicKey
+  config.api_key['X-Application-Key'] = 'YOUR API KEY'
+  # Uncomment the following line to set a prefix for the API key, e.g. 'Bearer' (defaults to nil)
+  # config.api_key_prefix['X-Application-Key'] = 'Bearer'
+end
+
+api_instance = Zyphr::AuthUserDirectoryApi.new
+user_id = '38400000-8cf0-11bd-b23e-10b96e4ef00d' # String | 
+
+begin
+  # Get an end user by id (server-side admin)
+  api_instance.get_end_user_by_id(user_id)
+rescue Zyphr::ApiError => e
+  puts "Error when calling AuthUserDirectoryApi->get_end_user_by_id: #{e}"
+end
+```
+
+#### Using the get_end_user_by_id_with_http_info variant
+
+This returns an Array which contains the response data (`nil` in this case), status code and headers.
+
+> <Array(nil, Integer, Hash)> get_end_user_by_id_with_http_info(user_id)
+
+```ruby
+begin
+  # Get an end user by id (server-side admin)
+  data, status_code, headers = api_instance.get_end_user_by_id_with_http_info(user_id)
+  p status_code # => 2xx
+  p headers # => { ... }
+  p data # => nil
+rescue Zyphr::ApiError => e
+  puts "Error when calling AuthUserDirectoryApi->get_end_user_by_id_with_http_info: #{e}"
+end
+```
+
+### Parameters
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **user_id** | **String** |  |  |
+
+### Return type
+
+nil (empty response body)
+
+### Authorization
+
+[ApplicationSecret](../README.md#ApplicationSecret), [ApplicationPublicKey](../README.md#ApplicationPublicKey)
+
+### HTTP request headers
+
+- **Content-Type**: Not defined
+- **Accept**: Not defined
+
+
+## get_end_user_claims
+
+> get_end_user_claims(user_id)
+
+Get an end user's stored custom claims (server-side admin)
+
+Secret-key-scoped read of the authoritative custom_claims stored for an end user. These are the TRUSTED claims embedded into the user's JWTs on login/refresh — use them (not the client-writable `metadata` field) for authorization decisions. Returns an empty object when none are set. 
+
+### Examples
+
+```ruby
+require 'time'
+require 'zyphr'
+# setup authorization
+Zyphr.configure do |config|
+  # Configure API key authorization: ApplicationSecret
+  config.api_key['X-Application-Secret'] = 'YOUR API KEY'
+  # Uncomment the following line to set a prefix for the API key, e.g. 'Bearer' (defaults to nil)
+  # config.api_key_prefix['X-Application-Secret'] = 'Bearer'
+
+  # Configure API key authorization: ApplicationPublicKey
+  config.api_key['X-Application-Key'] = 'YOUR API KEY'
+  # Uncomment the following line to set a prefix for the API key, e.g. 'Bearer' (defaults to nil)
+  # config.api_key_prefix['X-Application-Key'] = 'Bearer'
+end
+
+api_instance = Zyphr::AuthUserDirectoryApi.new
+user_id = '38400000-8cf0-11bd-b23e-10b96e4ef00d' # String | 
+
+begin
+  # Get an end user's stored custom claims (server-side admin)
+  api_instance.get_end_user_claims(user_id)
+rescue Zyphr::ApiError => e
+  puts "Error when calling AuthUserDirectoryApi->get_end_user_claims: #{e}"
+end
+```
+
+#### Using the get_end_user_claims_with_http_info variant
+
+This returns an Array which contains the response data (`nil` in this case), status code and headers.
+
+> <Array(nil, Integer, Hash)> get_end_user_claims_with_http_info(user_id)
+
+```ruby
+begin
+  # Get an end user's stored custom claims (server-side admin)
+  data, status_code, headers = api_instance.get_end_user_claims_with_http_info(user_id)
+  p status_code # => 2xx
+  p headers # => { ... }
+  p data # => nil
+rescue Zyphr::ApiError => e
+  puts "Error when calling AuthUserDirectoryApi->get_end_user_claims_with_http_info: #{e}"
+end
+```
+
+### Parameters
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **user_id** | **String** |  |  |
+
+### Return type
+
+nil (empty response body)
+
+### Authorization
+
+[ApplicationSecret](../README.md#ApplicationSecret), [ApplicationPublicKey](../README.md#ApplicationPublicKey)
+
+### HTTP request headers
+
+- **Content-Type**: Not defined
+- **Accept**: Not defined
+
+
+## invite_end_user
+
+> invite_end_user(invite_end_user_request)
+
+Pre-provision (invite) an end user (server-side admin)
+
+Secret-key-scoped pre-provisioning for an end user. Creates a passwordless user in the authenticating application (idempotent on email — an existing, non-deleted user is reused, not duplicated) and, when `send_link` is set, sends a first-login link so the user can set up their account without self-registration.  - `send_link: \"magic\"` sends a magic-link sign-in email. - `send_link: \"password_reset\"` sends a set-password email. - `send_link: \"none\"` (default) creates the user with no email.  A `redirect_url` is required when `send_link` is \"magic\" or \"password_reset\"; it must match the application's redirect_uris allowlist (custom schemes such as yourapp://path are permitted). 
+
+### Examples
+
+```ruby
+require 'time'
+require 'zyphr'
+# setup authorization
+Zyphr.configure do |config|
+  # Configure API key authorization: ApplicationSecret
+  config.api_key['X-Application-Secret'] = 'YOUR API KEY'
+  # Uncomment the following line to set a prefix for the API key, e.g. 'Bearer' (defaults to nil)
+  # config.api_key_prefix['X-Application-Secret'] = 'Bearer'
+
+  # Configure API key authorization: ApplicationPublicKey
+  config.api_key['X-Application-Key'] = 'YOUR API KEY'
+  # Uncomment the following line to set a prefix for the API key, e.g. 'Bearer' (defaults to nil)
+  # config.api_key_prefix['X-Application-Key'] = 'Bearer'
+end
+
+api_instance = Zyphr::AuthUserDirectoryApi.new
+invite_end_user_request = Zyphr::InviteEndUserRequest.new({email: 'email_example'}) # InviteEndUserRequest | 
+
+begin
+  # Pre-provision (invite) an end user (server-side admin)
+  api_instance.invite_end_user(invite_end_user_request)
+rescue Zyphr::ApiError => e
+  puts "Error when calling AuthUserDirectoryApi->invite_end_user: #{e}"
+end
+```
+
+#### Using the invite_end_user_with_http_info variant
+
+This returns an Array which contains the response data (`nil` in this case), status code and headers.
+
+> <Array(nil, Integer, Hash)> invite_end_user_with_http_info(invite_end_user_request)
+
+```ruby
+begin
+  # Pre-provision (invite) an end user (server-side admin)
+  data, status_code, headers = api_instance.invite_end_user_with_http_info(invite_end_user_request)
+  p status_code # => 2xx
+  p headers # => { ... }
+  p data # => nil
+rescue Zyphr::ApiError => e
+  puts "Error when calling AuthUserDirectoryApi->invite_end_user_with_http_info: #{e}"
+end
+```
+
+### Parameters
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **invite_end_user_request** | [**InviteEndUserRequest**](InviteEndUserRequest.md) |  |  |
+
+### Return type
+
+nil (empty response body)
+
+### Authorization
+
+[ApplicationSecret](../README.md#ApplicationSecret), [ApplicationPublicKey](../README.md#ApplicationPublicKey)
+
+### HTTP request headers
+
+- **Content-Type**: application/json
+- **Accept**: Not defined
+
+
+## list_end_users
+
+> list_end_users(opts)
+
+List / search end users (server-side admin)
+
+Secret-key-scoped directory listing of end users in the authenticating application. Supports substring search over email, name, and phone, an optional environment filter (test/live), and pagination. Scoped to the application — never returns users from another application. 
+
+### Examples
+
+```ruby
+require 'time'
+require 'zyphr'
+# setup authorization
+Zyphr.configure do |config|
+  # Configure API key authorization: ApplicationSecret
+  config.api_key['X-Application-Secret'] = 'YOUR API KEY'
+  # Uncomment the following line to set a prefix for the API key, e.g. 'Bearer' (defaults to nil)
+  # config.api_key_prefix['X-Application-Secret'] = 'Bearer'
+
+  # Configure API key authorization: ApplicationPublicKey
+  config.api_key['X-Application-Key'] = 'YOUR API KEY'
+  # Uncomment the following line to set a prefix for the API key, e.g. 'Bearer' (defaults to nil)
+  # config.api_key_prefix['X-Application-Key'] = 'Bearer'
+end
+
+api_instance = Zyphr::AuthUserDirectoryApi.new
+opts = {
+  page: 56, # Integer | 
+  per_page: 56, # Integer | 
+  search: 'search_example', # String | Substring match against email, name, or phone number.
+  environment: 'test' # String | 
+}
+
+begin
+  # List / search end users (server-side admin)
+  api_instance.list_end_users(opts)
+rescue Zyphr::ApiError => e
+  puts "Error when calling AuthUserDirectoryApi->list_end_users: #{e}"
+end
+```
+
+#### Using the list_end_users_with_http_info variant
+
+This returns an Array which contains the response data (`nil` in this case), status code and headers.
+
+> <Array(nil, Integer, Hash)> list_end_users_with_http_info(opts)
+
+```ruby
+begin
+  # List / search end users (server-side admin)
+  data, status_code, headers = api_instance.list_end_users_with_http_info(opts)
+  p status_code # => 2xx
+  p headers # => { ... }
+  p data # => nil
+rescue Zyphr::ApiError => e
+  puts "Error when calling AuthUserDirectoryApi->list_end_users_with_http_info: #{e}"
+end
+```
+
+### Parameters
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **page** | **Integer** |  | [optional][default to 1] |
+| **per_page** | **Integer** |  | [optional][default to 20] |
+| **search** | **String** | Substring match against email, name, or phone number. | [optional] |
+| **environment** | **String** |  | [optional] |
+
+### Return type
+
+nil (empty response body)
+
+### Authorization
+
+[ApplicationSecret](../README.md#ApplicationSecret), [ApplicationPublicKey](../README.md#ApplicationPublicKey)
+
+### HTTP request headers
+
+- **Content-Type**: Not defined
+- **Accept**: Not defined
+
+
+## set_end_user_claims
+
+> set_end_user_claims(user_id, set_end_user_claims_request)
+
+Set an end user's stored custom claims (server-side admin)
+
+Secret-key-scoped upsert of the authoritative custom_claims for an end user. Set server-side only — clients cannot write these, which is what makes them safe for authorization (e.g. an account-type/admin flag). Claims are embedded into the user's JWTs on the next login/refresh. Max 4KB; reserved JWT/Zyphr claim names are rejected.  To make a change take effect immediately on already-issued tokens (e.g. revoking admin), call POST /auth/sessions/revoke-all for the user after updating claims — that bumps the revocation epoch so outstanding access tokens stop verifying. 
+
+### Examples
+
+```ruby
+require 'time'
+require 'zyphr'
+# setup authorization
+Zyphr.configure do |config|
+  # Configure API key authorization: ApplicationSecret
+  config.api_key['X-Application-Secret'] = 'YOUR API KEY'
+  # Uncomment the following line to set a prefix for the API key, e.g. 'Bearer' (defaults to nil)
+  # config.api_key_prefix['X-Application-Secret'] = 'Bearer'
+
+  # Configure API key authorization: ApplicationPublicKey
+  config.api_key['X-Application-Key'] = 'YOUR API KEY'
+  # Uncomment the following line to set a prefix for the API key, e.g. 'Bearer' (defaults to nil)
+  # config.api_key_prefix['X-Application-Key'] = 'Bearer'
+end
+
+api_instance = Zyphr::AuthUserDirectoryApi.new
+user_id = '38400000-8cf0-11bd-b23e-10b96e4ef00d' # String | 
+set_end_user_claims_request = Zyphr::SetEndUserClaimsRequest.new # SetEndUserClaimsRequest | 
+
+begin
+  # Set an end user's stored custom claims (server-side admin)
+  api_instance.set_end_user_claims(user_id, set_end_user_claims_request)
+rescue Zyphr::ApiError => e
+  puts "Error when calling AuthUserDirectoryApi->set_end_user_claims: #{e}"
+end
+```
+
+#### Using the set_end_user_claims_with_http_info variant
+
+This returns an Array which contains the response data (`nil` in this case), status code and headers.
+
+> <Array(nil, Integer, Hash)> set_end_user_claims_with_http_info(user_id, set_end_user_claims_request)
+
+```ruby
+begin
+  # Set an end user's stored custom claims (server-side admin)
+  data, status_code, headers = api_instance.set_end_user_claims_with_http_info(user_id, set_end_user_claims_request)
+  p status_code # => 2xx
+  p headers # => { ... }
+  p data # => nil
+rescue Zyphr::ApiError => e
+  puts "Error when calling AuthUserDirectoryApi->set_end_user_claims_with_http_info: #{e}"
+end
+```
+
+### Parameters
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **user_id** | **String** |  |  |
+| **set_end_user_claims_request** | [**SetEndUserClaimsRequest**](SetEndUserClaimsRequest.md) |  |  |
+
+### Return type
+
+nil (empty response body)
+
+### Authorization
+
+[ApplicationSecret](../README.md#ApplicationSecret), [ApplicationPublicKey](../README.md#ApplicationPublicKey)
+
+### HTTP request headers
+
+- **Content-Type**: application/json
+- **Accept**: Not defined
+
+
+## update_end_user_by_application
+
+> update_end_user_by_application(user_id, update_end_user_by_application_request)
+
+Update an end user (server-side admin)
+
+Secret-key-scoped update of an arbitrary end user in the authenticating application. Updatable fields: email, name, avatar_url, metadata, status. Scoped to the application — a caller can never modify a user belonging to another application. 
+
+### Examples
+
+```ruby
+require 'time'
+require 'zyphr'
+# setup authorization
+Zyphr.configure do |config|
+  # Configure API key authorization: ApplicationSecret
+  config.api_key['X-Application-Secret'] = 'YOUR API KEY'
+  # Uncomment the following line to set a prefix for the API key, e.g. 'Bearer' (defaults to nil)
+  # config.api_key_prefix['X-Application-Secret'] = 'Bearer'
+
+  # Configure API key authorization: ApplicationPublicKey
+  config.api_key['X-Application-Key'] = 'YOUR API KEY'
+  # Uncomment the following line to set a prefix for the API key, e.g. 'Bearer' (defaults to nil)
+  # config.api_key_prefix['X-Application-Key'] = 'Bearer'
+end
+
+api_instance = Zyphr::AuthUserDirectoryApi.new
+user_id = '38400000-8cf0-11bd-b23e-10b96e4ef00d' # String | 
+update_end_user_by_application_request = Zyphr::UpdateEndUserByApplicationRequest.new # UpdateEndUserByApplicationRequest | 
+
+begin
+  # Update an end user (server-side admin)
+  api_instance.update_end_user_by_application(user_id, update_end_user_by_application_request)
+rescue Zyphr::ApiError => e
+  puts "Error when calling AuthUserDirectoryApi->update_end_user_by_application: #{e}"
+end
+```
+
+#### Using the update_end_user_by_application_with_http_info variant
+
+This returns an Array which contains the response data (`nil` in this case), status code and headers.
+
+> <Array(nil, Integer, Hash)> update_end_user_by_application_with_http_info(user_id, update_end_user_by_application_request)
+
+```ruby
+begin
+  # Update an end user (server-side admin)
+  data, status_code, headers = api_instance.update_end_user_by_application_with_http_info(user_id, update_end_user_by_application_request)
+  p status_code # => 2xx
+  p headers # => { ... }
+  p data # => nil
+rescue Zyphr::ApiError => e
+  puts "Error when calling AuthUserDirectoryApi->update_end_user_by_application_with_http_info: #{e}"
+end
+```
+
+### Parameters
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **user_id** | **String** |  |  |
+| **update_end_user_by_application_request** | [**UpdateEndUserByApplicationRequest**](UpdateEndUserByApplicationRequest.md) |  |  |
+
+### Return type
+
+nil (empty response body)
+
+### Authorization
+
+[ApplicationSecret](../README.md#ApplicationSecret), [ApplicationPublicKey](../README.md#ApplicationPublicKey)
+
+### HTTP request headers
+
+- **Content-Type**: application/json
+- **Accept**: Not defined
+