Jump to content

Help:Section/Editing sections of included templates

Add links
From Wikipedia, the free encyclopedia
< Help:Section
This is an old revision of this page, as edited by 184.103.50.131 (talk) at 02:18, 15 February 2023 (→Editing sections of included templates). The present address (URL) is a permanent link to this revision, which may differ significantly from the current revision.

Editing sections of included templates

This section appears in Help:Section.

The editing facilities can also be applied to a section of an included template. This section, Help:Editing sections of included templates, is an example.

For the purpose of section editing the extent of a section is governed by the headers in the calling page itself. It may consist of a part before the template tag, the template tag, and a part after the template tag, even if the template has sections.

It tends to be confusing if the extent of sections according to the system is different from what the rendered page suggests. To avoid this:

  • if a template has headers, do not put any text before the first header
  • in the calling page, start a new section after a template that itself has sections

It may be convenient, where suitable, to start a template with a section header, even if normally the contents of the template would not need a division into sections, and thus the template is only one section. The edit facilities for editing sections can then be used for editing the template from a page that includes it, without specially putting an edit link. This template is an example, it does not need a division into sections, but has a header at the top.

One downside with this solution is that you can't change the section level in the page that includes the template. This means that the section level you use in the template will be the same that is displayed on all your pages where you include the template, despite the fact that this might conflict with your intended hierarchy on the different pages.

Note that a parameter value appearing in a template, for example "{{{1}}}", is, if we want to preserve the parameter, not edited by editing the template but by editing the template call, even though the rendered page and its edit links do not automatically show that. Some explanatory text and/or an extra edit link can be useful. In this case, to edit "{{{1}}}" we have to edit the template tag on the page calling the template. If we use section editing the relevant section edit link is that at the header appearing before the header in the template itself.

The __NOEDITSECTION__ tag in any template affects both that template, the pages it's included on, and any other templates included on the same page.

{{fake heading}} can be used in templates and help pages where the appearance of a heading is desired without showing in the table of contents and without an edit link.

Xero Developer Home Ways to Build Docs Community

Sign up Log in

The Proof Key for Code Exchange (PKCE) flow The PKCE flow is required for applications like desktop and mobile apps that can’t securely store a client secret.

To get started, create and OAuth2.0 app and make sure you select the “Auth Code with PKCE” grant type. Your app will be assigned a unique Client ID but there will be no option to generate a client secret.

Single Page Apps (SPAs) are not currently supported.

Xero tenants Xero is a multi-tenanted platform with different types of tenants. Core Xero APIs (e.g. Accounting, Payroll, Files) operate within the context of an Organisation tenant but a tenant can also be a WorkflowMax account, a Practice Manager account or a XeroHQ practice. A user may have access to multiple tenants and will choose which ones to connect to your app. The type of tenant they can select will be determined by the scopes your app requests in the authorization step.

At the successful completion of an OAuth flow you will be granted an access token to act on behalf of the user. You will then use that access token to find out which tenants the user has connected to your app. From there, you can make API calls by providing both a valid access token and authorized tenant id with each request.


1. Send a user to authorize your app Your app should direct users to the following url:

https://login.xero.com/identity/connect/authorize?response_type=code&client_id=YOURCLIENTID&redirect_uri=YOURREDIRECTURI&scope=openid profile email accounting.transactions&state=123&code_challenge=XXXXXXXXX&code_challenge_method=S256

copy code The following values should be passed in as parameters:

response_type=code client_id issued when you create your app scope permissions to request (see below) redirect_uri the URL on your server to redirect back to state a unique string to be passed back on completion (optional) (see below) code_challenge The code challenge your app has generated as described below code_challenge_method=S256 Redirect URIs All redirect URIs must be https with the exception of localhost. Custom URL Schemes are not supported. Mobile clients should use Claimed HTTPS Scheme URI Redirection to register https redirect URIs. This is supported on both Android and iOS.

Scopes The scope parameter is a space-separated list of OAuth scopes, indicating what data you’d like your app to be able to access. You should request the minimum scopes required for whatever the user is doing at the time. The complete list of scopes can be found here.

State The state parameter should be used to avoid forgery attacks. Pass in a value that’s unique to the user you’re sending through authorisation. It will be passed back after the user completes authorisation.

Generating a code verifier and code challenge The first thing your app must do before starting an authorization request is generate a “code verifier”. A code verifier is a random string between 43 and 128 characters long that consists of the characters A-Z, a-z, 0-9, and the punctuation -._~ (hyphen, period, underscore, and tilde).

The “code challenge” is created by performing a SHA256 hash on the code verifier and then Base64url encoding the hash e.g.

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

copy code 2. Users are redirected back to you with a code If the user authorizes your app, Xero will redirect back to your specified redirect_uri with:

code a temporary code that may only be exchanged once and expires 5 minutes after issuance. state (if you provided one). If the states don’t match, the request may have been created by a third party and you should abort the process. If any errors occur or the user denies the request, we redirect back to your redirect_uri with an error parameter.

3. Exchange the code You can now exchange the verification code for an access token. You will also receive an identity token if you’ve requested OpenID Connect scopes and a refresh token if you’ve requested the offline_access scope.

To do this you will need to make a POST request to our token endpoint:

https://identity.xero.com/connect/token

copy code The request body will need to contain the grant type (authorization_code), client_id, code, redirect_uri and code verifier

grant_type=authorization_code client_id=The client ID of your app code=The authorization code you received in the callback redirect_uri=The same redirect URI that was used when requesting the code code_verifier=The code verifier that you created during the authorization step POST https://identity.xero.com/connect/token Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code &client_id=zzzzzzzz &code=xxxxxx &redirect_uri=https://myapp.com/redirect &code_verifier=yyyyyyy


copy code 4. Receive your tokens The token endpoint will verify all the parameters in the request, ensuring the code hasn’t expired and that the client ID matches. If everything checks out, it will generate your tokens and return them in the response.

It will contain the following parameters:

access_token The token used to call the API. id_tokenThe token containing user identity details (only returned if OpenID Connect scopes are requested). expires_inThe amount of seconds until the access token expires. token_type: Bearer refresh_tokenThe token used to refresh the access token once it has expired (only returned if the offline_access scope is requested). Token expiry All tokens received have an associated expiry time. Access tokens & refresh tokens can be exchanged prior to expiry.

Token expiry times:

id_token: 5 minutes access_token: 30 minutes refresh_token: 60 days The access token The access token is a JSON Web Token (JWT) which can be decoded to a JSON object containing information about the user and the authentication performed. One particularly useful value is the authentication_event_id which can be used in the next step to find out which tenant/s the user connected in the current auth flow.

{ 

   "nbf": 1589363023,
   "exp": 1589364823,
   "iss": "https://identity.xero.com",
   "aud": "https://identity.xero.com/resources",
   "client_id": "91E5715B1199038080D6D0296EBC1648",
   "sub": "a3a4dbafh3495a808ed7a7b964388f53",
   "auth_time": 1589361892,
   "xero_userid": "1945393b-6eb7-4143-b083-7ab26cd7690b",
   "global_session_id": "ac2202575e824af3a181c50fcaa65c3c",
   "jti": "4e7747cec4ce54d6512b4b0775166c5f",
   "authentication_event_id": "d0ddcf81-f942-4f4d-b3c7-f98045204db4",
   "scope": [
     "email",
     "profile",
     "openid",
     "accounting.transactions",
     "accounting.settings",
     "offline_access"
   ]
 }

copy code 5. Check the tenants you’re authorized to access Find out which tenants the user has authorized by calling the connections endpoint. If the user has authorized your app previously, they may have existing tenant connections. All of the connected tenants can now be accessed with the most recent access token.

If you want to retrieve the connection/s that were authorized in the current auth flow you can filter by the authEventId query parameter (e.g. ...?authEventId=d0ddcf81-f942-4f4d-b3c7-f98045204db4). You do this using the authentication_event_id found on the decoded access token.

Each connection will have a created date and an updated date. If they differ, that means the user has reconnected this tenant to your app (having previosuly connected and disconnected it).

GET https://api.xero.com/connections Authorization: "Bearer " + access_token Content-Type: application/json

Response: [ 

   {
       "id": "e1eede29-f875-4a5d-8470-17f6a29a88b1",
       "authEventId": "d99ecdfe-391d-43d2-b834-17636ba90e8d",
       "tenantId": "70784a63-d24b-46a9-a4db-0e70a274b056",
       "tenantType": "ORGANISATION",
       "tenantName": "Maple Florist",
       "createdDateUtc": "2019-07-09T23:40:30.1833130",
       "updatedDateUtc": "2020-05-15T01:35:13.8491980"
   },
   {
       "id": "32587c85-a9b3-4306-ac30-b416e8f2c841",
       "authEventId": "d0ddcf81-f942-4f4d-b3c7-f98045204db4",
       "tenantId": "e0da6937-de07-4a14-adee-37abfac298ce",
       "tenantType": "ORGANISATION",
       "tenantName": "Adam Demo Company (NZ)",
       "createdDateUtc": "2020-03-23T02:24:22.2328510",
       "updatedDateUtc": "2020-05-13T09:43:40.7689720"
   },
   {
       "id": "74305bf3-12e0-45e2-8dc8-e3ec73e3b1f9",
       "authEventId": "d0ddcf81-f942-4f4d-b3c7-f98045204db4",
       "tenantId": "c3d5e782-2153-4cda-bdb4-cec791ceb90d",
       "tenantType": "PRACTICEMANAGER",
       "tenantName": null,
       "createdDateUtc": "2020-01-30T01:33:36.2717380",
       "updatedDateUtc": "2020-02-02T19:21:08.5739590"
   }

]

copy code Remember! Uncertified apps can only connect to 25 tenants. Once you’ve got a few customers we recommend applying to become an app partner to have this limit removed.

6. Call the API Make calls against the Xero APIs by simply adding the following headers to your request:

Authorization: "Bearer " + access_token xero-tenant-id: tenantId GET ../api.xro/2.0/Invoices Authorization: "Bearer " + access_token Accept: application/json Xero-tenant-id: 45e4708e-d862-4111-ab3a-dd8cd03913e1


copy code Refreshing access & refresh tokens An access tokens expire after 30 minutes. Your app can refresh an access token without user interaction by using a refresh token. You get a refresh token by requesting the offline_access scope during the initial user authorization.

    • Note:**Your application must only request a refresh token if it is required and can be stored securely (e.g. in the keychain of the operating system).

To refresh your access token you need to POST to the token endpoint:

Remember! Uncertified apps can only connect to 25 tenants. Once you’ve got a few customers we recommend applying to become an app partner to have this limit removed.

https://identity.xero.com/connect/token

copy code The request body will need to contain the grant type and refresh token

grant_type=refresh_token client_id=Your client id refresh_token=Your refresh token POST https://identity.xero.com/connect/token Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token &client_id=zzzzzzz &refresh_token=xxxxxx


copy code The response will contain a new access token and refresh token. You must save both tokens in order to maintain api access.

If, for whatever reason, your app doesn’t receive the response, or fails to save the new token, you can retry using your existing refresh token for a grace period of 30 minutes. After 30 minutes your previous refresh token will expire and the user will need to re-authorise your api application in order to generate a new refresh token.

Removing connections If you would like to remove a tenant connection from your app (e.g. a user wants to disconnect one of their orgs) you can make a DELETE request on the Connections endpoint:

DELETE https://api.xero.com/connections/{connectionId}

copy code Revoking tokens You can revoke a user’s refresh token and remove all their connections to your app by making a request to the revocation endpoint.

To revoke a refresh token you need to POST to the revocation endpoint:

https://identity.xero.com/connect/revocation

copy code The request will require an authorization header containing your app’s client_id (client_secret is not required for PKCE apps).

Authorization: "Basic " + base64encode(client_id + ":") The request body will contain the refresh token being revoked

token=Your refresh token POST https://identity.xero.com/connect/revocation authorization: "Basic " + base64encode(client_id + ":") Content-Type: application/x-www-form-urlencoded

token=xxxxxx


copy code A successful revocation request will return a 200 response with an empty body.

Additional resources We have a Postman tutorial and an example .net windows forms app that demonstrate the PKCE flow in action.

Both of these can be found in the links below.

Postman Tutorial .net Windows Forms Sample App Explore Xero's APIs Accounting Assets Bank feeds Files Finance API Xero Payroll Practice Manager Xero Projects WorkflowMax Xero HQ Xero Developer Home

Search Sign up Log in Build Grow with Xero Build for Clients Docs OAuth SDKs and tools API reference How-to guides Webhooks Community Forum archive Feature request Find a developer GitHub Media News Dev blog Roadmap API status Support Our team Contact us FAQ Twitter YouTube Instagram About Xero We are hiring! Terms of Service Xero ecosystem principles Navigated to The Proof Key for Code Exchange (PKCE) flow

Retrieved from "https://en.wikipedia.org/w/index.php?title=Help:Section/Editing_sections_of_included_templates&oldid=1139426458"