Class: Assinafy::Resources::AuthResource

Inherits:
BaseResource show all
Defined in:
lib/assinafy/resources/auth_resource.rb,
sig/assinafy.rbs

Overview

Authentication and API key management.

See https://api.assinafy.com.br/v1/docs#authentication for the full documentation of these endpoints.

Constant Summary

Constants inherited from BaseResource

BaseResource::AUTH_HEADERS, BaseResource::PAGINATION_HEADERS, BaseResource::PATH_SEGMENT

Instance Method Summary collapse

Methods inherited from BaseResource

#initialize

Constructor Details

This class inherits a constructor from Assinafy::Resources::BaseResource

Instance Method Details

#change_password(email:, password:, new_password:) ⇒ Hash

Change the authenticated user's password.

Examples:

Request and response

resource.change_password(email: 'user@example.com', password: 'current-password',
                         new_password: 'new-password')
# Request body sent by the SDK:
#   { "email": "user@example.com", "password": "current-password",
#     "new_password": "new-password" }
#
# Returns the unwrapped data payload (envelope stripped):
# { "email" => "user@example.com" }

Parameters:

  • email (String)
  • password (String) —

    current password

  • new_password (String) —

    the new password to set

  • email: (String)
  • password: (String)
  • new_password: (String)

Returns:

  • (Hash) —

    unwrapped payload: { "email" => String }

See Also:

  • /authentication/change-password


193
194
195
196
197
198
199
200
 
# File 'lib/assinafy/resources/auth_resource.rb', line 193

def change_password(email:, password:, new_password:)
  call('Failed to change password') do
    @connection.put(
      'authentication/change-password',
      body_params(email: email, password: password, new_password: new_password)
    )
  end
end

#create_api_key(password:) ⇒ Hash

Generate a new API key for the authenticated user.

The returned key is shown in full only once, here; afterwards #get_api_key returns a masked version. IMPORTANT: generating a new key deletes (invalidates) the previous one. Send the key via the X-Api-Key header and never expose it in a front-end application.

Examples:

Request and response

resource.create_api_key(password: 'secret')
# Request body sent by the SDK:
#   { "password": "secret" }
#
# Returns the unwrapped data payload (envelope stripped):
# { "api_key" => "api-key-created-once" }

Parameters:

  • password (String) —

    the user's current password

  • password: (String)

Returns:

  • (Hash) —

    unwrapped payload: { "api_key" => String } (the new key, in full)

See Also:

  • /users/api-keys


123
124
125
126
127
 
# File 'lib/assinafy/resources/auth_resource.rb', line 123

def create_api_key(password:)
  call('Failed to create API key') do
    @connection.post('users/api-keys', body_params(password: password))
  end
end

#delete_api_key ⇒ nil

Delete the API key of the authenticated user.

The SDK ignores the response body and always returns nil on success. (The API itself responds with an empty data payload.)

Examples:

Request and response

resource.delete_api_key
# No request body (DELETE).
#
# Returns nil on success (the API's empty `data` payload is discarded).
# => nil

Returns:

  • (nil)

See Also:

  • /users/api-keys


169
170
171
172
173
 
# File 'lib/assinafy/resources/auth_resource.rb', line 169

def delete_api_key
  call_void('Failed to delete API key') do
    @connection.delete('users/api-keys')
  end
end

#get_api_key ⇒ Hash? Also known as: api_key

Retrieve the active API key for the authenticated user.

For security the key is returned MASKED (only the last 4 characters are visible); the full key is only available once, at #create_api_key time. Returns nil if no key has been generated yet. This endpoint works with X-Api-Key authentication (verified live), not only a Bearer token.

Examples:

Request and response (key exists)

resource.get_api_key
# No request body (GET).
#
# Returns the unwrapped data payload (envelope stripped):
# { "api_key" => "************************************************************9Jdr" }

Response when no key has been generated yet

resource.get_api_key # => nil

Returns:

  • (Hash, nil) —

    unwrapped payload: { "api_key" => String } (masked), or nil if no key exists yet

See Also:

  • /users/api-keys


147
148
149
150
151
 
# File 'lib/assinafy/resources/auth_resource.rb', line 147

def get_api_key
  call('Failed to get API key') do
    @connection.get('users/api-keys')
  end
end

#link_social_login(provider:, token:) ⇒ nil

Link a third-party identity provider to the authenticated user's account.

Examples:

Link a Google account

client.auth.(provider: 'google', token: 'provider-token')
# Request body sent by the SDK:
#   { "provider": "google", "token": "provider-token" }
# Response: { "status": 200, "message": "Provider linked" }
# => nil

Parameters:

  • provider (String) —

    the provider type; currently only google

  • token (String) —

    provider-issued OAuth/OIDC token

  • provider: (String)
  • token: (String)

Returns:

  • (nil) —

    the documented success envelope has no data payload

See Also:

  • /auth/link-social-login


99
100
101
102
103
 
# File 'lib/assinafy/resources/auth_resource.rb', line 99

def (provider:, token:)
  call('Failed to link social login') do
    @connection.post('auth/link-social-login', body_params(provider: provider, token: token))
  end
end

#login(email:, password:) ⇒ Hash

Authenticate with email and password.

The returned access_token is a JWT that typically expires in one hour. For long-lived back-end integrations, prefer an API key (see #create_api_key) over the access token.

Examples:

Request and response

resource.(email: 'user@example.com', password: 'secret')
# Request body sent by the SDK:
#   { "email": "user@example.com", "password": "secret" }
#
# Returns the unwrapped data payload (envelope { status, message, data } stripped):
# {
#   "access_token" => "access-token-placeholder",
#   "user" => {
#     "id" => "user-id", "name" => "Example User",
#     "email" => "user@example.com", "telephone" => "+15555550100",
#     "government_id" => "00000000000", "is_email_verified" => false,
#     "has_accepted_terms" => true, "created_at" => "2023-03-03T11:51:34Z",
#     "to_be_deleted_at" => nil
#   },
#   "accounts" => [
#     { "id" => "account-id", "name" => "Example Workspace", "roles" => ["owner"],
#       "is_delete_allowed" => true, "created_at" => "2023-03-03T11:51:34Z" }
#   ]
# }

Parameters:

  • email (String)
  • password (String)
  • email: (String)
  • password: (String)

Returns:

  • (Hash) —

    unwrapped payload: { "access_token" => String, "user" => Hash, "accounts" => Array }

Raises:

See Also:

  • /login


42
43
44
45
46
 
# File 'lib/assinafy/resources/auth_resource.rb', line 42

def (email:, password:)
  call('Failed to login') do
    http_post('login', body_params(email: email, password: password), workspace_auth: false)
  end
end

#request_password_reset(email:) ⇒ Hash

Trigger a password-reset email for the given account.

Used when the user forgot their password or has not set one yet. An email with a reset token is sent; pass that token to #reset_password to complete the flow.

Examples:

Request and response

resource.request_password_reset(email: 'user@example.com')
# Request body sent by the SDK:
#   { "email": "user@example.com" }
#
# Returns the unwrapped data payload (envelope stripped):
# { "email" => "user@example.com" }

Parameters:

  • email (String)
  • email: (String)

Returns:

  • (Hash) —

    unwrapped payload: { "email" => String }

See Also:

  • /authentication/request-password-reset


219
220
221
222
223
 
# File 'lib/assinafy/resources/auth_resource.rb', line 219

def request_password_reset(email:)
  call('Failed to request password reset') do
    http_put('authentication/request-password-reset', body_params(email: email), workspace_auth: false)
  end
end

#reset_password(email:, new_password:, token: nil) ⇒ Hash

Reset the password using the token sent via #request_password_reset.

Examples:

Request and response

resource.reset_password(email: 'user@example.com', new_password: 'new-password',
                        token: 'reset-token')
# Request body sent by the SDK (nil token would be omitted by body_params):
#   { "email": "user@example.com", "token": "reset-token", "new_password": "new-password" }
#
# Returns the unwrapped data payload (envelope stripped):
# { "email" => "user@example.com" }

Parameters:

  • email (String)
  • new_password (String) —

    the new password to set

  • token (String, nil) (defaults to: nil) —

    reset token from the email; omitted from the body when nil

  • email: (String)
  • new_password: (String)
  • token: (String, nil) (defaults to: nil)

Returns:

  • (Hash) —

    unwrapped payload: { "email" => String }

See Also:

  • /authentication/reset-password


242
243
244
245
246
247
248
249
250
 
# File 'lib/assinafy/resources/auth_resource.rb', line 242

def reset_password(email:, new_password:, token: nil)
  call('Failed to reset password') do
    http_put(
      'authentication/reset-password',
      body_params(email: email, token: token, new_password: new_password),
      workspace_auth: false
    )
  end
end

#social_login(provider:, token:, has_accepted_terms:) ⇒ Hash

Authenticate with a third-party identity provider token.

Currently the only supported provider is google. Returns the same shape as #login.

Examples:

Request and response

resource.(provider: 'google', token: 'provider-token', has_accepted_terms: true)
# Request body sent by the SDK:
#   { "provider": "google", "token": "provider-token", "has_accepted_terms": true }
#
# Returns the unwrapped data payload (envelope stripped); same shape as #login:
# {
#   "access_token" => "access-token-placeholder",
#   "user" => { "id" => "user-id", "name" => "Example User", ... },
#   "accounts" => [
#     { "id" => "account-id", "name" => "Example Workspace", "roles" => ["owner"],
#       "is_delete_allowed" => true, "created_at" => "2023-03-03T11:51:34Z" }
#   ]
# }

Parameters:

  • provider (String) —

    the provider type; currently only google

  • token (String) —

    provider-issued OAuth/OIDC access or ID token

  • has_accepted_terms (Boolean)
  • provider: (String)
  • token: (String)
  • has_accepted_terms: (Boolean)

Returns:

  • (Hash) —

    unwrapped payload: { "access_token" => String, "user" => Hash, "accounts" => Array }

See Also:

  • /authentication/social-login


73
74
75
76
77
78
79
80
81
82
83
84
85
 
# File 'lib/assinafy/resources/auth_resource.rb', line 73

def (provider:, token:, has_accepted_terms:)
  call('Failed to login with social provider') do
    http_post(
      'authentication/social-login',
      body_params(
        provider:           provider,
        token:              token,
        has_accepted_terms: has_accepted_terms
      ),
      workspace_auth: false
    )
  end
end