Magic Links

with magic links customers can seamlessly sign into your customer portal from your app or website magic links are a secure passwordless authentication mechanism that lets you securely generate urls to sign customers into your customer portal https //docs invoiced com/guides/billing portal this is perfect for redirecting users already authenticated within your app or service into your customer portal without the need for them to sign in once more generating magic links obtain your magic link key from the dashboard you can grab the secret key for generating magic links for your account in settings → developers → magic links within the dashboard warning keep your magic link key secret! it should only be used on servers under your control and never exposed in client side code generate a sign in token using your magic link key you can generate jwt tokens from your backend that tell us which customer to sign in build the url now you can plug your freshly generated token into a sign in url (replace yourcompany with your invoiced username) https //{yourcompany} invoiced com/login/{generated token} you can now link your freshly generated url from your website or else redirect users here page shortcuts when you sign your customer into the customer portal you can jump your customer into a sepcific page by adding a ?redirect to parameter to the magic link url if you do not specify this optional parameter then the user will be redirected to the my account page by default for example, to redirect your customer to the add payment method screen the resulting sign in url would look like this https //{yourcompany} invoiced com/login/{generated token}?redirect to=add payment method page page id my account my account credit notes list credit notes invoices list invoices estimates list estimates payments list payments balance forward statement (current month) balance forward statement open item statement open item statement pay balance pay add payment method add payment method update billing information update billing info generating jwt tokens with a client library import com invoiced util singlesignon; singlesignon magiclink = new singlesignon("{your magic link key}"); int customerid = 1234; int ttl = 3600; // 1 hour token = magiclink generatetoken(customerid, ttl);\<?php use invoiced\client; $invoiced = new client("{your api key}", false, "{your magic link key}"); $customerid = 1234; $ttl = 3600; // 1 hour $token = $client >generatesignintoken($customerid, $ttl); require "invoiced" client = invoiced client new("{your api key}", false, "{your magic link key}") customerid = 1234 ttl = 3600 # 1 hour token = client generate sign in token(customerid, ttl) generating magic links without a client library if you are using a language not supported with an official invoiced client library then you can still generate magic links the steps to generate a jwt token will vary by language, however, there are many open source libraries that make it a simple process any jwt tokens you generate should be signed using the hs256 algorithm with your magic link key the token should have the following parameters for the header { "alg" "hs256", "typ" "jwt" } and the following parameters for the payload { "sub" "{invoiced customer id}", "iss" "ruby backend", "exp" 1455564948 } the sub parameter should be the id of the customer on invoiced you are signing the user in as the iss parameter should be a string to identify the service that generated the token (any value works here) the exp parameter should be a unix timestamp https //en wikipedia org/wiki/unix time to indicate when the url should expire this will generate a token similar to this eyjhbgcioijiuzi1niisinr5cci6ikpxvcj9 eyjzdwiioiixmjm0nty3odkwiiwiaxnzijoiunviesbcywnrzw5kiiwizxhwijoxndu1nty0otq4fq lxu zcmtf8ikmsrrsvynp0szyrzuqqoaorhasdrfwps we recommend taking a look at jwt io https //jwt io to verify that tokens you generate are valid and to find client libraries in your language example here is an example showing how to generate a magic link in ruby with the jwt gem (as opposed to using the invoiced ruby library) require 'jwt' magic link key = '{magic link key from dashboard}' exp = time now + 86400 # link expires in 1 day payload = { \ sub => 1234, # invoiced customer id \ iss => "ruby backend", \ exp => exp to i } token = jwt encode payload, magic link key, 'hs256' \# eyj0exaioijkv1qilcjhbgcioijiuzi1nij9 eyjzdwiiojeymzqsimlzcyi6ilj1ynkgqmfja2vuzcisimv4cci6mtq1nty1mjixmh0 7kclq2uavez7xyus7zhgrepnzdg5mbrcgio6rzuo dw puts token url = "https //yourcompany invoiced com/login/#{token}" \# https //yourcompany invoiced com/login/eyj0exaioijkv1qilcjhbgcioijiuzi1nij9 eyjzdwiiojeymzqsimlzcyi6ilj1ynkgqmfja2vuzcisimv4cci6mtq1nty1mjixmh0 7kclq2uavez7xyus7zhgrepnzdg5mbrcgio6rzuo dw puts url