--- title: "Using the REST API" type: "wiki" space: "Axero Documentation" author: "Maxwell Drain" created: 2025-07-14T02:38:09Z updated: 2026-09-28T00:16:01Z tags: ["API"] url: "https://my.axerosolutions.com/spaces/5/axero-documentation/wiki/view/108975/using-the-rest-api" --- # Using the REST API This guide covers connecting another system to the Axero REST API: how to send a Bearer token, how to keep requests fast, and how to keep tokens safe. It applies whether you are moving an integration off a legacy API key or building a new one. * * * ## Authentication with Bearer Tokens The Axero REST API uses **Bearer tokens** for secure authentication. A Bearer token is cryptographically signed, which makes it harder to forge than a legacy API key. ### Basic Authentication Format After you create your Bearer token \([Creating Bearer Tokens](https://my.axerosolutions.com/spaces/5/axero-documentation/wiki/view/108973/creating-bearer-tokens "Creating Bearer Tokens")\), include it in the `Authorization` header \(a labeled line sent along with the request\) of every API request: **Request Format** ``` GET /api/users/me Host: yoursite.axero.com Authorization: Bearer YOUR_BEARER_TOKEN_HERE Content-Type: application/json ``` ### Migrating from Legacy API Keys The main change is the authorization header that every one of your API requests sends: **Legacy key, legacy header** ``` rest-api-key: YOUR_LEGACY_KEY_HERE ``` **Bearer token, recommended header** ``` Authorization: Bearer YOUR_BEARER_TOKEN_HERE ``` What is retired is the legacy key, not the header name. Axero also accepts a current bearer token in the `Rest-Api-Key` header, and supports that form on purpose. On a self-hosted site that uses Windows Authentication, the web server claims the `Authorization` header for its own sign-in exchange \(credential negotiation\) and refuses the request before Axero sees it. Sending the token as `Rest-Api-Key` leaves that header free and needs no server change, so try it first on such a site. The other route, opening anonymous access to the `/api` path alone, is described on [Active Directory SSO](https://my.axerosolutions.com/spaces/5/axero-documentation/wiki/view/19950/active-directory-sso "Active Directory SSO"). ### Self-Hosted Sites Everything on this page assumes the request reaches Axero. On a self-hosted site, the web server in front of Axero can refuse an API call first. This happens most often when Windows Authentication is on and Anonymous Authentication is off, which is the configuration [Active Directory SSO](https://my.axerosolutions.com/spaces/5/axero-documentation/wiki/view/19950/active-directory-sso "Active Directory SSO") sets up. A request refused there never reaches the token check, so no token change will clear it. Before troubleshooting a token, confirm the request reaches Axero at all. The 401 row in the status code table below explains how to tell. ### Implementation Examples These examples show how to send a Bearer token from different programming languages and tools: **cURL Example:** ``` curl -X GET "https://yoursite.axero.com/api/users/me" \ -H "Authorization: Bearer YOUR_BEARER_TOKEN_HERE" \ -H "Content-Type: application/json" ``` **JavaScript Example:** ``` fetch('https://yoursite.axero.com/api/users/me', { method: 'GET', headers: { 'Authorization': 'Bearer YOUR_BEARER_TOKEN_HERE', 'Content-Type': 'application/json' } }) .then(response => { if (!response.ok) { throw new Error(`HTTP error! status: ${response.status}`); } return response.json(); }) .then(data => console.log(data)) .catch(error => console.error('API Error:', error)); ``` **Python Example:** ``` import requests headers = { 'Authorization': 'Bearer YOUR_BEARER_TOKEN_HERE', 'Content-Type': 'application/json' } try: response = requests.get('https://yoursite.axero.com/api/users/me', headers=headers) response.raise_for_status() # Raises an HTTPError for bad responses data = response.json() print(data) except requests.exceptions.RequestException as e: print(f"API Error: {e}") ``` ### CRITICAL SECURITY WARNING #### DO NOT Embed API Keys or Bearer Tokens in Client-Side Code **When building widgets or content pages for your Axero site:** - **NEVER** embed API keys or bearer tokens in widgets or content pages - **NEVER** include tokens in JavaScript code that runs in the browser - **NEVER** expose tokens in HTML source code or client-side applications **Security Risk:** End users can find any API key or bearer token embedded in client-side code \(code that runs in their browser\), which creates significant security vulnerabilities. Anyone can view page source, inspect network requests, or use browser developer tools to extract these credentials. #### SECURE AUTHENTICATION APPROACHES #### Internal API Usage \(Within Your Axero Platform\) **For widgets, content pages, and client-side JavaScript within your Axero site:** - **Do not include any authentication token.** Omit the `Authorization` header completely - Axero automatically signs the request in as the current user, using their session - This keeps the call secure and limited to that user's permissions **Example:** An API call from a JavaScript widget automatically gets the signed-in user's permissions, with no token needed. #### External API Usage \(Outside Your Axero Platform\) **For server-to-server integrations, external applications, and third-party systems:** - **Always use Bearer tokens** in the `Authorization: Bearer {token}` header - Keep tokens on your servers, stored with proper credential management - Make sure no end user can reach a token and no token appears in client-side code **Example:** External applications connecting to your Axero API must authenticate with Bearer tokens to access data on behalf of specific users. * * * ## API Usage Guidelines and Best Practices Axero does not enforce hard rate limits on the REST API by default; the one exception is Axero Functions, where each function has its own limit. \(A rate limit caps how many requests you can send in a given time.\) Follow the practices below anyway, so your integration stays fast and the site stays responsive for everyone else. If heavy API use slows down the whole site, Axero may temporarily restrict your request rate. ### Request Rate Guidelines - **Maximum Request Rate:** Do not exceed **5 API calls per second** sustained - **Concurrent Requests:** Limit to **3 or fewer concurrent connections** - **Response Time Validation:** During testing, check that each API response completes within **15 seconds** - **Sequential Processing:** In automated workflows, wait for each request to finish before sending the next one ### Performance Optimization - **Implement Intelligent Caching:** Store data you read often on your own side, with a suitable TTL \(Time To Live, how long a saved copy is kept before you fetch it again\) - **Use Efficient Pagination:** Retrieve large datasets in smaller pages, using the pagination parameters - **Apply Smart Filtering:** Use query parameters to request only the specific data you need - **Optimize Request Timing:** Schedule bulk operations during off-peak hours when possible ### Common HTTP Status Codes | Status Code | Meaning | Action | | :--- | :--- | :--- | | `200` | Success | Process the response data | | `401` | Unauthorized | Look at the shape of the response first. If a 401 carries a reason phrase and a short or empty body, it came from Axero: check or refresh the token. If a 401 comes back as a full HTML error page, the web server in front of the site refused the request before Axero saw it, and the token is not involved. On a self-hosted site, see [Active Directory SSO](https://my.axerosolutions.com/spaces/5/axero-documentation/wiki/view/19950/active-directory-sso "Active Directory SSO"). | | `403` | Forbidden | The account lacks permission for this action, or the feature it calls is switched off on the site. A 403 can also come from a firewall, content delivery network, or proxy in front of the site, and then Axero never saw the request. | | `429` | Too Many Requests | Axero sends this only when a call that runs an Axero Function goes over that function's own rate limit; wait the number of seconds in the `Retry-After` header, then retry. A 429 from any other call came from a service in front of the site: wait and retry, making the wait longer after each failed attempt \(exponential backoff\) | | `500` | Server Error | Retry after a delay; contact support if the error persists | * * * ## API Categories The Axero REST API is grouped into categories, one for each area of your intranet. Each category below links to the pages for its endpoints \(the individual addresses a program calls\): ### Users API Create, update, and manage user accounts and roles. #### Key Features - Retrieve user profiles and account information - Create and manage user accounts - Assign and update user roles and permissions - Search and filter users by various criteria - Manage user membership in spaces and groups - Update user points and recognition metrics #### Common Use Cases - **User Synchronization:** Import users from existing HR systems or databases - **Automated Onboarding:** Create user accounts when new employees join - **Role Management:** Update user roles when employees change positions - **Directory Integration:** Sync user information with Active Directory or LDAP **Documentation:** [REST API: Users](https://my.axerosolutions.com/spaces/5/axero-documentation/wiki/view/371/rest-api-users "REST API: Users") ### Content API Create, retrieve, and manage every type of content on your intranet. #### Key Features - Create and publish articles, blog posts, and other content types - Retrieve content lists with filtering and sorting options - Manage content categories and tags - Handle file uploads and attachments - Access workflow and approval queues - Manage content permissions and visibility #### Common Use Cases - **Content Syndication:** Display community content on external websites or digital signage - **Automated Publishing:** Create content from external systems or feeds - **Content Migration:** Import existing content from other platforms - **Custom Dashboards:** Build personalized content views and recommendations **Documentation:** [REST API: Content](https://my.axerosolutions.com/spaces/5/axero-documentation/wiki/view/374/rest-api-content "REST API: Content") ### Spaces API Manage the spaces that organize your intranet into departments, teams, or project areas. #### Key Features - Create and configure new spaces - Retrieve space information and metadata - Manage space membership and access controls - Assign and update space-specific roles - Configure space settings and permissions - Organize spaces in hierarchical structures #### Common Use Cases - **Organizational Structure:** Mirror your company's department structure in digital spaces - **Project Management:** Create temporary spaces for specific projects or initiatives - **Access Control:** Manage who can access sensitive or department-specific information - **Automated Provisioning:** Create spaces automatically based on external triggers **Documentation:** [REST API: Spaces](https://my.axerosolutions.com/spaces/5/axero-documentation/wiki/view/372/rest-api-spaces "REST API: Spaces") ### Chat API Connect real-time chat messaging to external systems and workflows. #### Key Features - Send and receive chat messages - Create and manage chat threads - Add participants to conversations - Retrieve message history and thread information #### Common Use Cases - **Workflow Integration:** Trigger chat notifications from external systems - **Customer Support:** Route support requests to appropriate chat channels - **Automated Messaging:** Send system notifications or reminders via chat - **Cross-Platform Communication:** Bridge conversations between different systems **Documentation:** [REST API: Chat](https://my.axerosolutions.com/spaces/5/axero-documentation/wiki/view/29840/rest-api-chat "REST API: Chat") ### Comments API Manage comments and discussions on every content type in your intranet. #### Key Features - Create and post comments on content - Retrieve comment threads and individual comments - Edit and update existing comments - Delete comments and manage moderation - Set comment status and approval workflows - Manage comment permissions and visibility #### Common Use Cases - **Feedback Collection:** Gather input and opinions on proposals or ideas - **Moderation Automation:** Implement automated comment filtering and approval - **Engagement Analytics:** Track discussion patterns and user engagement - **Content Enhancement:** Add contextual information or updates via comments **Documentation:** [REST API: Comments](https://my.axerosolutions.com/spaces/5/axero-documentation/wiki/view/4844/rest-api-comments "REST API: Comments") ### Permissions API Check and manage user permissions and role-based access across your intranet. #### Key Features - Check user permissions for specific actions or content - Update role permissions and access levels - Validate access rights before performing operations - Manage permission inheritance and overrides #### Common Use Cases - **Access Validation:** Verify user permissions before displaying content or features - **Role Management:** Programmatically update permissions when organizational roles change - **Custom Authorization:** Implement complex permission logic in external applications **Documentation:** [REST API: Permissions](https://my.axerosolutions.com/spaces/5/axero-documentation/wiki/view/25127/rest-api-permissions "REST API: Permissions") ### Workflows API Set up the approval steps that content passes through before it is published, with each step assigned to a role, in one space or at site level. #### Key Features - List workflows across every space, or filter by space, content type, or status - Read one workflow with its steps in approval order - Create a workflow and its steps in one request - Replace a workflow's name, description, status, and steps in one request - Add, reassign, move, or remove a single approval step - Delete a workflow that is not the default and has no content waiting for approval #### Common Use Cases - **Approval Auditing:** Review which spaces require approval and which roles approve at each step - **Automated Provisioning:** Create a space's approval workflow from another system when the space is set up - **Bulk Updates:** Reassign an approval step to a different role across many workflows at once **Documentation:** [REST API: Workflows](https://my.axerosolutions.com/spaces/5/axero-documentation/wiki/view/113471/rest-api-workflows "REST API: Workflows") ### Recognition API Use employee recognition and gamification to build engagement and celebrate achievements. #### Key Features - Award badges and recognition to users - Retrieve recognition programs and available badges - Access challenge and leaderboard data - Get user-specific recognition insights and achievements #### Common Use Cases - **External Integration:** Award recognition when users complete tasks in other systems - **Performance Tracking:** Integrate recognition data with HR or performance management systems - **Automated Recognition:** Trigger awards based on specific behaviors or milestones - **Gamification:** Build custom leaderboards and achievement systems **Documentation:** [REST API: Recognition](https://my.axerosolutions.com/spaces/5/axero-documentation/wiki/view/81467/rest-api-recognition "REST API: Recognition") ### Analytics API Read the engagement and content reports your intranet collects. #### Key Features - Retrieve content engagement metrics and analytics - Access user activity and participation data - Get space-specific analytics and usage patterns - Track trending content and popular topics - Monitor community health and engagement metrics #### Common Use Cases - **Custom Dashboards:** Build executive dashboards with community metrics - **Content Strategy:** Identify trending topics and high-performing content - **User Engagement:** Track and reward the most active community members - **ROI Reporting:** Measure community impact and business value **Documentation:** [REST API: Analytics](https://my.axerosolutions.com/spaces/5/axero-documentation/wiki/view/85193/rest-api-analytics "REST API: Analytics") ## Getting Help If you need help, [open a support case](https://my.axerosolutions.com/spaces/77/axero-online-support/cases/add-edit-case/0) and include the following information: - **API Endpoint:** The specific endpoint and HTTP method \(e.g., `GET /api/users/me`\) - **Request Headers:** Include all headers, but redact your actual token - **Request Body:** The request payload, if the request has one - **Error Response:** The complete error message and its HTTP status code - **Network Environment:** Any firewalls, proxies, or network restrictions #### Related pages - [Creating Bearer Tokens](https://my.axerosolutions.com/spaces/5/axero-documentation/wiki/view/108973/creating-bearer-tokens "Creating Bearer Tokens") \(to create the token this page tells you how to send\) - [Enabling API Access](https://my.axerosolutions.com/spaces/5/axero-documentation/wiki/view/108972/enabling-api-access "Enabling API Access") \(if you are the administrator who has to switch the API on first\) - [Active Directory SSO](https://my.axerosolutions.com/spaces/5/axero-documentation/wiki/view/19950/active-directory-sso "Active Directory SSO") \(if your site is self-hosted and every call comes back 401 whatever token you send\)