Double activation: get machine ID

[nschloe]

When activating a machine for a license, the API will return the machine ID:

{
    'data': {
        'id': '...',
        'type': 'machines',
        'attributes': {
            'fingerprint': '...',
             # ...
}

When trying to activate the same machine a second time, the call fails with

{
    'meta': {'id': '...'},
    'errors': [
        {
            'title': 'Unprocessable resource',
            'detail': 'has already been taken',
            'code': 'FINGERPRINT_TAKEN',
            # ...
        }
    ]
}

I don't know why this is an error. Will it also error out if the same machine tries to activate a different license (with the same machine fingerprint)?

Also, what's the meta.id here? I had assumed the machine ID, but apparently it's not. Do I have to search machines by fingerprint to get the ID?

[ezekg]

You're receiving an error because you can't activate a machine that is already activated. Typically, if you're doing this, then your activation flow is incorrect. Please follow this activation flow, i.e. you should validate the license before activating the current machine, to check if it's already activated and valid. If it's already valid, there's no need to attempt to activate the machine again.

Regardless — you can list the license's current machines if you need to find a particular machine. Or yes, you can also lookup a machine by its fingerprint when authenticated as the license:

GET /v1/accounts/<account>/machines/<fingerprint>

And whether or not a fingerprint can be shared across licenses is determined by the policy's fingerprint uniqueness strategy.

Lastly, the meta.id is a reference ID. It is the request log's ID, so you/we can lookup the request that caused the error.

[nschloe]

Here's a little survey of possible outcomes:

• License with no required fingerprinting:

  • validate with fingerprint:
    • err, NO_MACHINE
  • validate without fingerprint:
    • VALID
  • activate:
    • err, LICENSE_NOT_ALLOWED
      (License key authentication is not allowed by policy)
      Edit: Success!

• License which DOES require fingerprinting:

  • validate with fingerprint:
    • VALID
    • err, NO_MACHINE
  • validate without fingerprint:
    • err, FINGERPRINT_SCOPE_REQUIRED
  • activate:
    • success
    • err, MACHINE_LIMIT_EXCEEDED
    • err, FINGERPRINT_TAKEN

At validation with fingerprint, I wish there was a way to tell apart those licenses in which the machine is missing (NO_MACHINE) and those where in principle no machine can be added. The latter case is only revealed on activation now. I don't know now how to produce FINGERPRINT_SCOPE_MISMATCH.

[ezekg]

@nschloe there is no such thing as a non-fingerprinted license. Any license can have activations, even if the policy does not necessarily require it. If you include a fingerprint scope, the validation request will assert that scope — no matter what. There is no way to reject scopes from the policy. It's very simple: if you don't want a validation to use a scope, don't send one. Your application or SDK will need to know when and when not to send a fingerprint.

If the license has no machines, a NO_MACHINE(S) failure code will be returned (plurality depending on if the policy is floating). If the machine does have machines, but none of the fingerprints match, a FINGERPRINT_SCOPE_MISMATCH failure code is returned. Ultimately, if the policy is strict, then an activation will always be required.

More information on the various codes are available here.

Lastly — the LICENSE_NOT_ALLOWED error code indicates that the policy does not allow license key authentication. You need to set your policy's authentication strategy to LICENSE or MIXED.

[nschloe]

Thanks for the reply! I'll dive back into it tomorrow.

[nschloe]

Okay, I think I got it now:

• You can do license activation, validation with fingerprints etc no matter if the license has Require fingerprint scope or not.
• The demo account failed my fingerprinted validation request (key validation fails if specifying fingerprint on non-fingerprinted key #63) not because it in principle doesn't support it. It failed because I provided a fingerprint, and that fingerprint isn't in the list of activated machines for that license (FINGERPRINT_SCOPE_MISMATCH). If the demo license had had no activated licenses at all, the error code would've been NO_MACHINE/NO_MACHINES.

I could in principle share code paths between licenses that do require fingerprinting and those that don't. Just always activate and validate with fingerprint.

The cleaner approach would certainly be to store the info about fingerprint requirement somewhere with the key, e.g., with a prefix.

[ezekg]

That is correct. 👍

You could also use metadata on the license to determine whether or not to activate, since that information would be available after validation and before activation, via the validation response body.