class GdsApi::AccountApi

@api documented
@see github.com/alphagov/account-api<br><br>Adapter for the Account API

def auth_headers(govuk_account_session) 

def auth_headers(govuk_account_session)
  { AUTH_HEADER_NAME => govuk_account_session }
end

def check_for_email_subscription(govuk_account_session:)

Returns:
  • (Hash) - Whether the user has a subscription, and a new session header

Parameters:
  • govuk_account_session (String) -- Value of the session header 
def check_for_email_subscription(govuk_account_session:)
  get_json("#{endpoint}/api/transition-checker-email-subscription", auth_headers(govuk_account_session))
end

def create_registration_state(attributes:)

Returns:
  • (Hash) - The state ID to pass to get_sign_in_url

Parameters:
  • attributes (Hash, nil) -- Initial attributes to store 
def create_registration_state(attributes:)
  post_json("#{endpoint}/api/oauth2/state", attributes: attributes)
end

def delete_email_subscription(name:, govuk_account_session:)

Parameters:
  • govuk_account_session (String) -- Value of the session header
  • name (String) -- Name of the subscription 
def delete_email_subscription(name:, govuk_account_session:)
  delete_json("#{endpoint}/api/email-subscriptions/#{CGI.escape(name)}", {}, auth_headers(govuk_account_session))
end

def delete_saved_page(page_path:, govuk_account_session:)

Returns:
  • (GdsApi::Response) - A status code of 204 indicates the saved page has been successfully deleted.

Parameters:
  • govuk_account_session (String) -- Value of the session header
  • the (String) -- path of a page to check 
def delete_saved_page(page_path:, govuk_account_session:)
  delete_json("#{endpoint}/api/saved-pages/#{CGI.escape(page_path)}", {}, auth_headers(govuk_account_session))
end

def get_attributes(attributes:, govuk_account_session:)

Returns:
  • (Hash) - The attribute values (if present), and a new session header

Parameters:
  • govuk_account_session (String) -- Value of the session header
  • attributes (String) -- Names of the attributes to check 
def get_attributes(attributes:, govuk_account_session:)
  querystring = nested_query_string({ attributes: attributes }.compact)
  get_json("#{endpoint}/api/attributes?#{querystring}", auth_headers(govuk_account_session))
end

def get_attributes_names(attributes:, govuk_account_session:)

Returns:
  • (Hash) - The attribute names (if present), and a new session header

Parameters:
  • govuk_account_session (String) -- Value of the session header
  • attributes (String) -- Names of the attributes to check 
def get_attributes_names(attributes:, govuk_account_session:)
  querystring = nested_query_string({ attributes: attributes }.compact)
  get_json("#{endpoint}/api/attributes/names?#{querystring}", auth_headers(govuk_account_session))
end

def get_email_subscription(name:, govuk_account_session:)

Returns:
  • (Hash) - Details of the subscription, if it exists.

Parameters:
  • govuk_account_session (String) -- Value of the session header
  • name (String) -- Name of the subscription 
def get_email_subscription(name:, govuk_account_session:)
  get_json("#{endpoint}/api/email-subscriptions/#{CGI.escape(name)}", auth_headers(govuk_account_session))
end

def get_saved_page(page_path:, govuk_account_session:)

Returns:
  • (Hash) - containing :saved_page, a hash of a single saved page value

Parameters:
  • govuk_account_session (String) -- Value of the session header
  • the (String) -- path of a page to check 
def get_saved_page(page_path:, govuk_account_session:)
  get_json("#{endpoint}/api/saved-pages/#{CGI.escape(page_path)}", auth_headers(govuk_account_session))
end

def get_saved_pages(govuk_account_session:)

Returns:
  • (Hash) - containing :saved_pages, an array of single saved page hashes

Parameters:
  • govuk_account_session (String) -- Value of the session header 
def get_saved_pages(govuk_account_session:)
  get_json("#{endpoint}/api/saved-pages", auth_headers(govuk_account_session))
end

def get_sign_in_url(redirect_path: nil, state_id: nil, level_of_authentication: nil)

Returns:
  • (Hash) - An authentication URL and the OAuth state parameter (for CSRF protection)

Parameters:
  • level_of_authentication (String, nil) -- either "level1" (require MFA) or "level0" (do not require MFA)
  • state_id (String, nil) -- identifier originally returned by #create_registration_state
  • redirect_path (String, nil) -- path on GOV.UK to send the user to after authentication 
def get_sign_in_url(redirect_path: nil, state_id: nil, level_of_authentication: nil)
  querystring = nested_query_string(
    {
      redirect_path: redirect_path,
      state_id: state_id,
      level_of_authentication: level_of_authentication,
    }.compact,
  )
  get_json("#{endpoint}/api/oauth2/sign-in?#{querystring}")
end

def get_user(govuk_account_session:)

Returns:
  • (Hash) - Information about the user and the services they've used, and a new session header

Parameters:
  • govuk_account_session (String) -- Value of the session header 
def get_user(govuk_account_session:)
  get_json("#{endpoint}/api/user", auth_headers(govuk_account_session))
end

def nested_query_string(params) 

def nested_query_string(params)
  Rack::Utils.build_nested_query(params)
end

def put_email_subscription(name:, topic_slug:, govuk_account_session:)

Returns:
  • (Hash) - Details of the newly created subscription.

Parameters:
  • govuk_account_session (String) -- Value of the session header
  • topic_slug (String) -- The email-alert-api topic slug to subscribe to
  • name (String) -- Name of the subscription 
def put_email_subscription(name:, topic_slug:, govuk_account_session:)
  put_json("#{endpoint}/api/email-subscriptions/#{CGI.escape(name)}", { topic_slug: topic_slug }, auth_headers(govuk_account_session))
end

def save_page(page_path:, govuk_account_session:)

Returns:
  • (Hash) - A single saved page value (if sucessful)

Parameters:
  • govuk_account_session (String) -- Value of the session header
  • the (String) -- path of a page to check 
def save_page(page_path:, govuk_account_session:)
  put_json("#{endpoint}/api/saved-pages/#{CGI.escape(page_path)}", {}, auth_headers(govuk_account_session))
end

def set_attributes(attributes:, govuk_account_session:)

Returns:
  • (Hash) - A new session header

Parameters:
  • govuk_account_session (String) -- Value of the session header
  • attributes (String) -- Hash of new attribute values 
def set_attributes(attributes:, govuk_account_session:)
  patch_json("#{endpoint}/api/attributes", { attributes: attributes }, auth_headers(govuk_account_session))
end

def set_email_subscription(govuk_account_session:, slug:)

Returns:
  • (Hash) - Whether the user has a subscription, and a new session header

Parameters:
  • slug (String) -- The email topic slug
  • govuk_account_session (String) -- Value of the session header 
def set_email_subscription(govuk_account_session:, slug:)
  post_json("#{endpoint}/api/transition-checker-email-subscription", { slug: slug }, auth_headers(govuk_account_session))
end

def update_user_by_subject_identifier(subject_identifier:, email: nil, email_verified: nil, has_unconfirmed_email: nil)

Returns:
  • (Hash) - The user's subject identifier and email attributes

Parameters:
  • has_unconfirmed_email (Boolean, nil) -- Whether the user has a new, pending, email address
  • email_verified (Boolean, nil) -- Whether the user's current email address is verified
  • email (String, nil) -- The user's current
  • subject_identifier (String) -- The identifier of the user, shared between the auth service and GOV.UK. 
def update_user_by_subject_identifier(subject_identifier:, email: nil, email_verified: nil, has_unconfirmed_email: nil)
  params = {
    email: email,
    email_verified: email_verified,
    has_unconfirmed_email: has_unconfirmed_email,
  }.compact
  patch_json("#{endpoint}/api/oidc-users/#{subject_identifier}", params)
end

def validate_auth_response(code:, state:)

Returns:
  • (Hash) - The value for the govuk_account_session header, the path to redirect the user to, and the GA client ID (if there is one)

Parameters:
  • state (String) -- The OAuth state parameter, from the auth server.
  • code (String) -- The OAuth code parameter, from the auth server. 
def validate_auth_response(code:, state:)
  post_json("#{endpoint}/api/oauth2/callback", code: code, state: state)
end