There are two methods to authenticate the GoCanvas API (application program interface). By default, each call placed to the API accepts the username and password of an authorized GoCanvas user as required parameters. The second option is to set up an API Key at the account or department level and pass a token inside the header of your request with a username as the parameter.
Configuring API Keys
To enable the API Key feature and create an API Key, follow these steps:
- Go to Account > Account Settings.
- Scroll down to the Security Settings > API Keys and click Settings.
- On this page, check the box to Enable API Keys and then click Create API Key. (Note: If you utilize Departments in your account, you will specify which Department the API Key is associated with upon creating the API Key. If you choose "All", the token will have access to all Department data.)
- Enter a Key Name and click Save.
- GoCanvas will generate a unique API Key that you must copy and store somewhere safe to use in your API calls (Note: Characters will not be blurred as seen in this image).
Once you have created the API Key, you will use API calls by passing the token inside the header of your request. The username parameter is mandatory, otherwise a "Permission Denied for the requested resource" error will be returned by the API calls. When you use API Keys, you'll no longer be able to access the API (including Zapier and Business Insights) with just your username and password.
Curl Request Format:
curl -H "Authorization: Bearer NapDjG*****************************************" localhost:3000/apiv2/forms.xml -F 'username=test_user@gocanvas.com'
HTTP Request Format:
Request Headers:
Authorization:"Bearer NapDjG**************************************"
Request Body:
username:" test_user@gocanvas.com"
Comments
30 comments
"When you use API Keys, you'll no longer be able to access the API with just your username and password"
----------------
......and this means that you cannot use API keys and also have Business Insights or Zapier running on your GoCanvas account
GoCanvas requires users to chose between having API keys activated and using Business Insights/Zapier.
That's true for now. We're looking into fixing that and I will update here when I know more.
Whats the likely time-line to seeing a fix?
Hi Sara - do you have a time frame for this?
Hi Dave,
I don't have a time frame, but it is actively and intensely being worked on. The goal is to get it out ASAP. I'll let you know when I hear about an ETA.
Is there any more news on this one?
Hey Dave,
The BI fix will be out this month - it's being tested right now. I'm waiting on an answer about the Zapier timeline and will report back.
What is API endpoint? How can I use this api_key in Python code?
Hi Dhruvit,
An endpoint is one end of an API communication channel, which usually ends up being a URL. Here's a nice definition from stack overflow:
An endpoint is the 'connection point' of a service, tool, or application accessed over a network. In the world of software, any software application that is running and "listening" for connections uses an endpoint as the "front door." When you want to connect to the application/service/tool to exchange data you connect to its endpoint.
So you'd point something in python to the GoCanvas endpoint in order to pull data from the system. Hope that helps!
Hi Sara,
The API / Username / Password fix must be ready to go live? Any updates you can share?
Hey Dave,
The new version of Business Insights is ready, but hasn't officially been released. I can send that to you directly if you'd like, while we wait for the download link to be updated. The Zapier fix is still in the works, and I'm trying to get a timeline on that.
Yes, that would be good as well as any documentation that goes with it.
HI Sara - just checking in on this one again. Have not received anything.
Hey Dave, just sent it again - it should come through looking like a support ticket. Let me know if you're not seeing it still. Thanks!
Have downloaded and briefly had a look at the new Business Insights plugin for excel that was part of the GoCanvas API fix.
From what I can see it works in the following way:
Surprised to see the improvement was to make an API key necessary in excel rather than making a change on the GoCanvas end to allow both methods access.
Struggling to see an efficient process for how we hand out and manage security of API keys. Be interested to get GoCanvas thoughts on how you see this being managed.
Sara - Did you have a chance to have a look at this one?
Hey Dave, sorry for the lack of reply. I'm checking with a colleague on if what you described is the expected functionality and will report back.
Hi Sara - any more news on this one?
Hey Dave,
I've been told that what you've described is the expected behavior. As you said, once you have API keys activated, that's the only way to access things that rely on the API (which both Business Insights and Zapier do). I do realize this makes things tough if multiple people are trying to use Business Insights. I'd recommend having one person have ownership over who gets/needs an API key and try to limit that as much as possible. I'd also make sure to be very precise with naming the keys, to reduce confusion and make it easier to maintain. I'll keep poking around about this, but I do think it's unlikely we'll have a hybrid solution coming soon.
I really hope this is being escalated in your business. Even if we were to go to the effort of maintaining a system that issues an API key per user needing excel access and as you put use “very precise with naming the keys” there is a significant security risk.
I don’t feel I should need to explain this to GoCanvas but the fact that I’m not getting response in Australia to my emails and the delays and gaps with what is being written here suggests it is not understood.
When an API key is issued in GoCanvas it is essentially a common password for all users with access. If someone has the api key they need only have a guess at an email address that has that access and they now pull down ever record, upload etc.
If departments are activated it may be contained to a department otherwise it is across the business.
Is there anyone in GoCanvas I can follow this up with?
You're welcome to put in a feature request (I know you had one for using API keys with BI and Zapier, but this is more specific so I'd either amend that one or put in a new one) or surface it with your Account Manager.
The challenge is that this combination of feature usage - API keys and multiple users needing to access Business Insights - is incredibly uncommon. I will bring it up again with the product manager who oversees integrations, but I can't make any promises that this is something that will be addressed. He's on vacation, but I'll connect with him when he's back in the office.
I do apologize for the bigger gaps here. That's on my team, and we'll work on improving responses in the Help Center.
Replies here won't generally come during AU hours, however, as the Help Center and Community are maintained by a US-based team separate from Support. We do have a Support Team in Australia, so you'll get answers to tickets in AU business hours, but not responses to posts here (unless we can't sleep).
The gap here isn’t that GoCanvas isn’t responding in AU business hours it’s that responses don’t come in days, weeks and in some instance months and that I need to keep prompting again and again. If you look back at the posts the times and dates support this. This will be seen throughout any number of other posts for myself and others.
This issue we are talking about has been raised at length locally with account management without result.
If it is necessary for me to raise another feature request I can do that for you. This will be for the exact same issue though.
Regarding the the comment that API Keys and multiple users needing access Business Insights is incredibly uncommon...... I would suggest that this is because the current offering of business insights and API keys means that not only would make this be uncommon but it is impossible by design.
Given this manager is on vacation is there someone else in the business this issue can be referred to?
Hi Dave,
As I said, I will take it up with the product owner when he returns, and I have escalated it to his team in the meantime. I don't think we're likely to make adjustments to the way this works, but I will talk through what you're encountering and hopefully be able to provide a more technical explanation as to why we've gone this route sometime next week.
The use case isn't limited because the functionality isn't there, but rather that we have a very small group of users who have implemented API keys, and a small group of users using Business Insights (which gets even smaller if you're talking about multiple users having access to the tool), and so the potential for overlap is therefore even smaller.
With regards to the long periods of no response, that's simply because there's nothing to report. If a request is chosen for development and gets to the point where we're ready to talk about it publicly, the post will get updated. Until then, you can assume that they aren't actively being worked on or are far enough out to not merit an update.
Hi Dave,
I wanted to follow up here. I brought some folks together internally to try to understand why we implemented API keys this way and what our technical folks would recommend for your use case. Here's what we came to:
1. We initially built API keys based on specific requirements from one of our customers, which we then validated with other customer interviews. No one else that we talked to during the requirements-gathering process needed to use both API keys and username/password, which is why we limited the scope to using just the webservices API, not API in combination with either Zapier or Business Insights.
2. As for what they recommend, it basically came down to either managing API keys or not using the feature. One thing we had users do before API keys was use a single username and password on the account for API access. So instead of connecting the API using an actual person's account (which can cause issues with security, people changing their passwords, etc.), we can create a free user on your account that can specifically be used for the API hookup. Then you can continue using BI and have a less fragile API setup without using API keys. Let me know if you're interested in that.
Thanks,
Sara
Hi Sara,
Hope you are doing well , I just recently got access in canvas , iam doing an API call in Python with JSON dict, do you have a documentation for that? Atleast an example of get response.
Hi Chip,
Hope you are doing well, i already posted on the community page , i need an example of a screenshot of how to have the url in python with API, confused with the username and where o provide. Your help will be highly appreciated as iam trying to do an API call and create a dataframe for analysis and comparing with other Database we are using with.
Regards,
Raj.
Howdy Raj,
Thank you for sharing this feedback in the Community! I reached out to our Engineering team on this matter. They shared that we don't return JSON to any API calls, only XML.
You will need to send a header in their request using the key value pair Authorization : [API Key]. As far as how to send a header, or how to structure an API call using Python to reach one of our API endpoints, we don't have any screenshots or examples available.
Hopefully other users in the Community have examples or screenshots they can share on your Community post here.
It would be great if we could use both the username/password API requests and the API key requests at the same time. We have dozens of apps syncing data and there is no way to switch all of them over to the API keys at once. An API key for authentication seems like the better, more industry standard approach, but because of this limitation it seems impossible to migrate to it without serious headaches.
It needs to be possible to do both at the same time. Ideally once the API key is enabled, there would be another option to disable to the username/password once all of the programs using the API have been updated.
It would also be easier to switch to the API key if it worked as query string parameters like the username and password method does. Putting the key in the headers and the username in the body requires additional programming to modify the interfaces.
I would like to switch to the API key, but have not because there is no way to test it without interrupting the current interfaces, and it is more complicated due to the header and body requirements.
It would not be as bad that the username and password method stops working if it used query string parameters, because it would be a simple change to the URL.
Please implement this change. Need both API and username/password. Paying a lot of money for the service and the loops we need to jump through to get the data back are crazy
Please sign in to leave a comment.