Answers.Body: <p>While <a href="https://docs.civicrm.org/dev/en/latest/framework/authx/" rel="nofollow noreferrer">the documentation</a> can be confusing, I wouldn't say it's lacking.  I want to make sure you found this particular page, particularly the &quot;Guards&quot; section.</p>
  <p>In APIv3, you use a site key and an API key.  That API key corresponds to a particular user in the database (stored in <code>civicrm_contact</code> table).  AuthX adds two new permissions - <code>authenticate with password</code> and <code>authenticate with api key</code>.  The &quot;User Permission&quot; guard ensures that only users with one of those permissions can use the APIv4 endpoint.  This is almost certainly (one of) the causes of your 401 error.</p>
  <p>There are many formats for passing the site key now, too many to effectively answer here.  Personally, I put it in the body of a POST request with a key of <code>key</code>, but you should still be able to pass it in as a GET param like in APIv3.</p>
  <p><a href="https://i.sstatic.net/zcgfa.png" rel="nofollow noreferrer"><img src="https://i.sstatic.net/zcgfa.png" alt="CMS permission settings for AuthX" /></a></p>
  
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2022-09-14T12:51:29.293Z
Answers.Text: Hi, thanks, I've seen that page many times.  No where does it say how or where to add the user permissions it refers to.  There's also only one reference to site key, and it's for "legacy rest".  Furthermore, the Authentication plugin clearly has two options for Auth Guard: "User Permission" and "Site Key".  That is not the same as "with password" and "with API key".  Please clarify.
Answers.UserDisplayName: Mmm
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2022-09-14T13:32:34.580Z
Answers.Text: @mmm I separated the explanation of "User Permission" and "Site Key" into separate paragraphs - please edit if you think it's unclear!  "User Permission" means, "This user has the `authenticate with api key` permission and I am passing their API key" - or they have `authenticate with password` and you're passing in a password.  It's unrelated to the site key question.  The [Flows](https://docs.civicrm.org/dev/en/latest/framework/authx/#flows) section explains how you can pass the values in - e.g. `Authorization:` header, `X-Civi-Auth:` header, etc.
Answers.UserDisplayName: Jon G - Megaphone Tech
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2022-09-14T14:04:41.660Z
Answers.Text: This doesn't jive with what I'm seeing.  I'm using X-Civi-Auth with an API key for an admin, and it works if I do NOT have Auth Guard enabled.  If I add "user permission", I get 401 with the API key.  Unless there's a "authenticate with API permission" setting somewhere?  I still do not see how to pass the site key anywhere.  My original question still stands.  What permission is this, and how do you add it?  How do you pass the site key?
Answers.UserDisplayName: Mmm
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2022-09-14T15:33:44.337Z
Answers.Text: Sorry you're not seeing them - I don't know what CMS you're using but Civi permissions are integrated with the CMS.  I added a screenshot of https://mysite.com/admin/people/permissions on Drupal 7 demonstrating that the permissions are present.  If you're using WordPress, I recommend going to Civi's **Administer menu » Users and Permissions » Permissions** and editing it there, WP's native permission editing sucks without a plugin.
Answers.UserDisplayName: Jon G - Megaphone Tech
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2022-09-14T15:38:51.837Z
Answers.Text: Alright!  We are using Drupal, and your screenshot + link answered part 1.  Part 2 is how do I use the site key?  There are no working examples that I've found for APIv4.
Answers.UserDisplayName: Mmm
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2022-09-14T15:40:20.113Z
Answers.Text: OK, glad we're making progress!  The site key is defined in `civicrm.settings.php`, which should be in `<webroot>/sites/default`.
Answers.UserDisplayName: Jon G - Megaphone Tech
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2022-09-14T16:02:36.837Z
Answers.Text: I know the sitekey.  I use it for APIv3.  What I don't know is how to use it in APIv4, hence my question.
Answers.UserDisplayName: Mmm
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2022-09-14T16:09:40.390Z
Answers.Text: You pass it in as a URL argument with a key of `key` (works with GET and POST) or as a POST body request with a key of `key`.  Here's a `curl` statement demonstrating the first approach: `curl -X POST https://mysite/civicrm/ajax/rest\?entity\=job\&action\=execute\&key\=<sitekey>\&api_key\=<apikey>\&json\=1\&version\=3 -H 'X-Requested-With: XMLHttpRequest'`. You can see an Ansible command that I use to generate a POST request using the second approach here: https://github.com/MegaphoneJon/ansible-main/blob/81a527ae24ea9ff541fd4452605c75bdbb7e7cc5/shutup.yml#L21-L33
Answers.UserDisplayName: Jon G - Megaphone Tech
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2022-09-14T16:50:50.627Z
Answers.Text: Let us [continue this discussion in chat](https://chat.stackexchange.com/rooms/139200/discussion-between-mmm-and-jon-g-megaphone-tech).
Answers.UserDisplayName: Mmm
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2022-09-14T12:15:41.120Z
Answers.LastActivityDate: 2022-09-14T15:34:08.073Z
Answers.LastEditDate: 2022-09-14T15:34:08.073Z
Answers.UserDisplayName: Jon G - Megaphone Tech
Body: <p>I'm working on converting an app that was built against the REST APIv3 to use REST APIv4, and I've found the APIv4 documentation quite lacking.</p>
  <p>Through trial and error, I've determined that Authentication Guard has to be effectively disabled (by having it configured with no options in the Authentication Extension) for CiviCRM to authenticate my call.  All other options I've tried return 401 Unauthorized.  (Note to others: Make sure you're using a recent version of CiviCRM.  While APIv4 has existed for quite some time, the REST part of it appears to have been added around v5.47.)</p>
  <p>There are two options that can be enabled, that are not mutually exclusive:</p>
  <ol>
  <li>User Permission.  What permission is this, and how do you add it?</li>
  <li>Site Key.  How do you include the Site Key in your APIv4 REST call?  The format used for APIv3 does not appear to work.</li>
  </ol>
  <p>My question is: How do you leverage Authentication Guard in your APIv4 calls?</p>
  <p>Thanks.</p>
  
Tags: <rest><apiv4><authentication>
Title: How to leverage Authentication Guard for APIv4 calls
ThreadText: # How to leverage Authentication Guard for APIv4 calls
  
  (Asked by: username_0 on 2022-09-13)
  
  I'm working on converting an app that was built against the REST APIv3 to use REST APIv4, and I've found the APIv4 documentation quite lacking.
  
  Through trial and error, I've determined that Authentication Guard has to be effectively disabled (by having it configured with no options in the Authentication Extension) for CiviCRM to authenticate my call. All other options I've tried return 401 Unauthorized. (Note to others: Make sure you're using a recent version of CiviCRM. While APIv4 has existed for quite some time, the REST part of it appears to have been added around v5.47.)
  
  There are two options that can be enabled, that are not mutually exclusive:
  
  1. User Permission. What permission is this, and how do you add it?
  2. Site Key. How do you include the Site Key in your APIv4 REST call? The format used for APIv3 does not appear to work.
  
  My question is: How do you leverage Authentication Guard in your APIv4 calls?
  
  Thanks.
  
  **Tags:** rest, apiv4, authentication
  
  
  ---
  
  ## 1 answers
  
  ### Answer by username_1 on 2022-09-14. Score: 1
  
  While [the documentation](https://docs.civicrm.org/dev/en/latest/framework/authx/) can be confusing, I wouldn't say it's lacking. I want to make sure you found this particular page, particularly the "Guards" section.
  
  In APIv3, you use a site key and an API key. That API key corresponds to a particular user in the database (stored in `civicrm_contact` table). AuthX adds two new permissions - `authenticate with password` and `authenticate with api key`. The "User Permission" guard ensures that only users with one of those permissions can use the APIv4 endpoint. This is almost certainly (one of) the causes of your 401 error.
  
  There are many formats for passing the site key now, too many to effectively answer here. Personally, I put it in the body of a POST request with a key of `key`, but you should still be able to pass it in as a GET param like in APIv3.
  
  [![CMS permission settings for AuthX](https://i.sstatic.net/zcgfa.png)](https://i.sstatic.net/zcgfa.png)
  
  > **Comments:**
  > **username_0**: Hi, thanks, I've seen that page many times.  No where does it say how or where to add the user permissions it refers to.  There's also only one reference to site key, and it's for "legacy rest".  Furthermore, the Authentication plugin clearly has two options for Auth Guard: "User Permission" and "Site Key".  That is not the same as "with password" and "with API key".  Please clarify.  
  > **username_1**: @mmm I separated the explanation of "User Permission" and "Site Key" into separate paragraphs - please edit if you think it's unclear!  "User Permission" means, "This user has the `authenticate with api key` permission and I am passing their API key" - or they have `authenticate with password` and you're passing in a password.  It's unrelated to the site key question.  The [Flows](https://docs.civicrm.org/dev/en/latest/framework/authx/#flows) section explains how you can pass the values in - e.g. `Authorization:` header, `X-Civi-Auth:` header, etc.  
  > **username_0**: This doesn't jive with what I'm seeing.  I'm using X-Civi-Auth with an API key for an admin, and it works if I do NOT have Auth Guard enabled.  If I add "user permission", I get 401 with the API key.  Unless there's a "authenticate with API permission" setting somewhere?  I still do not see how to pass the site key anywhere.  My original question still stands.  What permission is this, and how do you add it?  How do you pass the site key?  
  > **username_1**: Sorry you're not seeing them - I don't know what CMS you're using but Civi permissions are integrated with the CMS.  I added a screenshot of https://mysite.com/admin/people/permissions on Drupal 7 demonstrating that the permissions are present.  If you're using WordPress, I recommend going to Civi's **Administer menu » Users and Permissions » Permissions** and editing it there, WP's native permission editing sucks without a plugin.  
  > **username_0**: Alright!  We are using Drupal, and your screenshot + link answered part 1.  Part 2 is how do I use the site key?  There are no working examples that I've found for APIv4.  
  > **username_1**: OK, glad we're making progress!  The site key is defined in `civicrm.settings.php`, which should be in `<webroot>/sites/default`.  
  > **username_0**: I know the sitekey.  I use it for APIv3.  What I don't know is how to use it in APIv4, hence my question.  
  > **username_1**: You pass it in as a URL argument with a key of `key` (works with GET and POST) or as a POST body request with a key of `key`.  Here's a `curl` statement demonstrating the first approach: `curl -X POST https://mysite/civicrm/ajax/rest\?entity\=job\&action\=execute\&key\=<sitekey>\&api_key\=<apikey>\&json\=1\&version\=3 -H 'X-Requested-With: XMLHttpRequest'`. You can see an Ansible command that I use to generate a POST request using the second approach here: https://github.com/MegaphoneJon/ansible-main/blob/81a527ae24ea9ff541fd4452605c75bdbb7e7cc5/shutup.yml#L21-L33  
  > **username_0**: Let us [continue this discussion in chat](https://chat.stackexchange.com/rooms/139200/discussion-between-mmm-and-jon-g-megaphone-tech).  
  
  ---
  
  